tweak docs

Author: ArunPiduguDD

changelog.d/tag_cardinality_limit_tracking_scope.enhancement.md

@@ -1,18 +1,20 @@
 The `tag_cardinality_limit` transform gained two new top-level settings:
 
 - **`tracking_scope`** controls how tag tracking state is partitioned across metrics:
-  - `global` (default — preserves existing behavior): all metrics share a single
-    tracking bucket, and the global `value_limit` caps the combined set of tag values
-    across them.
+  - `global` (default — preserves existing behavior): all tags share a single
+    tracking bucket across metrics, and the global `value_limit` caps this combined
+    set of tag values them.
   - `per_metric`: every distinct metric gets its own tracking bucket, providing tag
     cardinality limiting for each metric in isolation at the cost of higher memory.
 
 - **`max_tracked_keys`** caps the total number of distinct (metric, tag-key) pairs
   tracked across the entire transform. When the cap is reached, additional pairs are
-  not allocated and tag values for those pairs pass through unchecked (they are
-  *not* dropped). Operators can detect this via the new
-  `tag_cardinality_untracked_events_total` counter (incremented once per event with at
-  least one untracked tag) and the `tag_cardinality_tracked_keys` gauge (current size
-  of the cardinality cache). Defaults to unlimited, preserving existing behavior.
+  are not tracked and tag values for those pairs pass through unchecked.
+  - Users can detect this via the new
+    `tag_cardinality_untracked_events_total` counter (incremented once per event with at
+    least one untracked tag) and the `tag_cardinality_tracked_keys` gauge (current size
+    of the cardinality cache). Defaults to unlimited, preserving existing behavior.
+  - When using `max_tracked_key` with global tracking scope, the specified cap
+    will still apply (e.g. tags will be tracked as (<null>, tag-key))
 
 authors: ArunPiduguDD

src/transforms/tag_cardinality_limit/config.rs

@@ -43,12 +43,13 @@ pub struct Config {
     /// Maximum number of distinct (metric, tag-key) pairs to track across the entire
     /// transform. When this cap is reached, additional tag keys on new metrics or new
     /// tag keys on existing metrics are not tracked, and tag values for those pairs
-    /// pass through unchecked. Operators can detect this via the
+    /// pass through unchecked. users can detect this via the
     /// `tag_cardinality_untracked_events_total` counter and the
     /// `tag_cardinality_tracked_keys` gauge.
-    ///
+
     /// When unset (default), there is no cap and the transform tracks all pairs it
-    /// encounters.
+    /// encounters. In `global` tracking scope mode, this limit still applies (the
+    /// metric key is set to `None` unless there is a per-metric override)
     #[configurable(derived)]
     #[serde(default)]
     pub max_tracked_keys: Option<usize>,
@@ -68,8 +69,8 @@ pub struct Config {
 #[serde(rename_all = "snake_case")]
 pub enum TrackingScope {
     /// All metrics share a single tracking bucket. Tag values pool across metrics,
-    /// and the global `value_limit` caps the combined set. Lower memory but
-    /// cross-metric pollution.
+    /// and the global `value_limit` caps the combined set. Lower memory requirements
+    /// but cardinality per metric is not tracked unless a per-metric override is configured.
     #[default]
     Global,
 

website/cue/reference/components/transforms/generated/tag_cardinality_limit.cue

@@ -45,12 +45,12 @@ generated: components: transforms: tag_cardinality_limit: configuration: {
 			Maximum number of distinct (metric, tag-key) pairs to track across the entire
 			transform. When this cap is reached, additional tag keys on new metrics or new
 			tag keys on existing metrics are not tracked, and tag values for those pairs
-			pass through unchecked. Operators can detect this via the
+			pass through unchecked. users can detect this via the
 			`tag_cardinality_untracked_events_total` counter and the
 			`tag_cardinality_tracked_keys` gauge.
-
 			When unset (default), there is no cap and the transform tracks all pairs it
-			encounters.
+			encounters. In `global` tracking scope mode, this limit still applies (the
+			metric key is set to `None` unless there is a per-metric override)
 			"""
 		required: false
 		type: uint: {}
@@ -162,8 +162,8 @@ generated: components: transforms: tag_cardinality_limit: configuration: {
 			enum: {
 				global: """
 					All metrics share a single tracking bucket. Tag values pool across metrics,
-					and the global `value_limit` caps the combined set. Lower memory but
-					cross-metric pollution.
+					and the global `value_limit` caps the combined set. Lower memory requirements
+					but cardinality per metric is not tracked unless a per-metric override is configured.
 					"""
 				per_metric: """
 					Every distinct metric gets its own tracking bucket, providing tag