docs: improve docs for `persist_partition_size_threshold_bytes` / `INFLUXDB_IOX_PERSIST_PARTITION_SIZE_THRESHOLD_BYTES` (#4877)

* docs: improve docs for `persist_partition_size_threshold_bytes` / `INFLUXDB_IOX_PERSIST_PARTITION_SIZE_THRESHOLD_BYTES`

* docs: improve comments about LifecycleConfig::partition_size_threshold

Co-authored-by: kodiakhq[bot] <49736102+kodiakhq[bot]@users.noreply.github.com>

clap_blocks/src/ingester.rs

@@ -37,8 +37,12 @@ pub struct IngesterConfig {
     )]
     pub persist_memory_threshold_bytes: usize,
 
-    /// If an individual partition crosses this size threshold, it will be persisted.
-    /// The default value is 300MB (in bytes).
+    /// If the total bytes written to an individual partition crosses
+    /// this size threshold, it will be persisted.  The default value
+    /// is 300MB (in bytes).
+    ///
+    /// NOTE: This number is related, but *NOT* the same as the size
+    /// of the memory used to keep the partition buffered.
     #[clap(
         long = "--persist-partition-size-threshold-bytes",
         env = "INFLUXDB_IOX_PERSIST_PARTITION_SIZE_THRESHOLD_BYTES",

influxdb_iox/src/commands/run/all_in_one.rs

@@ -208,8 +208,12 @@ pub struct Config {
     )]
     pub persist_memory_threshold_bytes: usize,
 
-    /// If an individual partition crosses this size threshold, it will be persisted.
-    /// The default value is 300MB (in bytes).
+    /// If the total bytes written to an individual partition crosses
+    /// this size threshold, it will be persisted.  The default value
+    /// is 300MB (in bytes).
+    ///
+    /// NOTE: This number is related, but *NOT* the same as the size
+    /// of the memory used to keep the partition buffered.
     #[clap(
         long = "--persist-partition-size-threshold-bytes",
         env = "INFLUXDB_IOX_PERSIST_PARTITION_SIZE_THRESHOLD_BYTES",

ingester/src/lifecycle.rs

@@ -136,8 +136,14 @@ pub struct LifecycleConfig {
     /// partitions currently buffered until it falls below this threshold. An ingester running
     /// in a steady state should operate around this amount of memory usage.
     persist_memory_threshold: usize,
-    /// If an individual partition crosses this threshold, it will be persisted. The purpose of this
-    /// setting to to ensure the ingester doesn't create Parquet files that are too large.
+    /// If the total bytes written to an individual partition crosses
+    /// this threshold, it will be persisted.
+    ///
+    /// NOTE: This number is related, but *NOT* the same as the size
+    /// of the memory used to keep the partition buffered.
+    ///
+    /// The purpose of this setting to to ensure the ingester doesn't
+    /// create Parquet files that are too large.
     partition_size_threshold: usize,
     /// If an individual partitiion has had data buffered for longer than this period of time, the
     /// manager will persist it. This setting is to ensure we have an upper bound on how far back