chore(docs): Clarify key_field for sample and throttle transforms (#17372)

* chore(docs): Clarify `key_field` for `sample` and `throttle` transforms

The current wording is somewhat confusing. I'm hopeful that this new wording is more clear.

Signed-off-by: Jesse Szwedko <[email protected]>

* Apply suggestions from code review

Co-authored-by: neuronull <[email protected]>

---------

Signed-off-by: Jesse Szwedko <[email protected]>
Co-authored-by: neuronull <[email protected]>

Author: jszwedko

src/transforms/sample.rs

@@ -27,12 +27,17 @@ pub struct SampleConfig {
     /// dropped.
     pub rate: u64,
 
-    /// The name of the log field whose value is hashed to determine if the event should be
-    /// passed.
+    /// The name of the field whose value is hashed to determine if the event should be
+    /// sampled.
     ///
-    /// Consistently samples the same events. Actual rate of sampling may differ from the configured
-    /// one if values in the field are not uniformly distributed. If left unspecified, or if the
-    /// event doesn't have `key_field`, then events are count rated.
+    /// Each unique value for the key creates a bucket of related events to be sampled together
+    /// and the rate is applied to the buckets themselves to sample `1/N` buckets.  The overall rate
+    /// of sampling may differ from the configured one if values in the field are not uniformly
+    /// distributed. If left unspecified, or if the event doesn’t have `key_field`, then the
+    /// event is sampled independently.
+    ///
+    /// This can be useful to, for example, ensure that all logs for a given transaction are
+    /// sampled together, but that overall `1/N` transactions are sampled.
     #[configurable(metadata(docs::examples = "message",))]
     pub key_field: Option<String>,
 

src/transforms/throttle.rs

@@ -33,11 +33,9 @@ pub struct ThrottleConfig {
     #[serde_as(as = "serde_with::DurationSeconds<f64>")]
     window_secs: Duration,
 
-    /// The name of the log field whose value is hashed to determine if the event should be
-    /// rate limited.
+    /// The value to group events into separate buckets to be rate limited independently.
     ///
-    /// Each unique key creates a bucket of related events to be rate limited separately. If
-    /// left unspecified, or if the event doesn't have `key_field`, then the event is not rate
+    /// If left unspecified, or if the event doesn't have `key_field`, then the event is not rate
     /// limited separately.
     #[configurable(metadata(docs::examples = "{{ message }}", docs::examples = "{{ hostname }}",))]
     key_field: Option<Template>,

website/cue/reference/components/transforms/base/sample.cue

@@ -8,12 +8,17 @@ base: components: transforms: sample: configuration: {
 	}
 	key_field: {
 		description: """
-			The name of the log field whose value is hashed to determine if the event should be
-			passed.
+			The name of the field whose value is hashed to determine if the event should be
+			sampled.
 
-			Consistently samples the same events. Actual rate of sampling may differ from the configured
-			one if values in the field are not uniformly distributed. If left unspecified, or if the
-			event doesn't have `key_field`, then events are count rated.
+			Each unique value for the key creates a bucket of related events to be sampled together
+			and the rate is applied to the buckets themselves to sample `1/N` buckets. Overall rate
+			of sampling may differ from the configured one if values in the field are not uniformly
+			distributed. If left unspecified, or if the event doesn’t have `key_field`, then the
+			event is sampled independently.
+
+			This can be useful to, for example, ensure that all logs for a given transaction are
+			sampled together, but that overall `1/N` transactions are sampled.
 			"""
 		required: false
 		type: string: examples: ["message"]

website/cue/reference/components/transforms/base/throttle.cue

@@ -8,11 +8,9 @@ base: components: transforms: throttle: configuration: {
 	}
 	key_field: {
 		description: """
-			The name of the log field whose value is hashed to determine if the event should be
-			rate limited.
+			The value to group events into a separate buckets to be rate limited independently.
 
-			Each unique key creates a bucket of related events to be rate limited separately. If
-			left unspecified, or if the event doesn't have `key_field`, then the event is not rate
+			If left unspecified, or if the event doesn't have `key_field`, then the event is not rate
 			limited separately.
 			"""
 		required: false