Skip to content

Commit

Permalink
chore(docs): Clarify key_field for sample and throttle transfor…
Browse files Browse the repository at this point in the history
…ms (vectordotdev#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 <jesse.szwedko@datadoghq.com>

* Apply suggestions from code review

Co-authored-by: neuronull <neuronull@pm.me>

---------

Signed-off-by: Jesse Szwedko <jesse.szwedko@datadoghq.com>
Co-authored-by: neuronull <neuronull@pm.me>
  • Loading branch information
jszwedko and neuronull authored May 12, 2023
1 parent 7350e1a commit d1e5588
Show file tree
Hide file tree
Showing 4 changed files with 24 additions and 18 deletions.
15 changes: 10 additions & 5 deletions src/transforms/sample.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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>,

Expand Down
6 changes: 2 additions & 4 deletions src/transforms/throttle.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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>,
Expand Down
15 changes: 10 additions & 5 deletions website/cue/reference/components/transforms/base/sample.cue
Original file line number Diff line number Diff line change
Expand Up @@ -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"]
Expand Down
6 changes: 2 additions & 4 deletions website/cue/reference/components/transforms/base/throttle.cue
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down

0 comments on commit d1e5588

Please sign in to comment.