refactor(tag_cardinality_limit): simplify per-tag config to LimitOverride/Excluded enum

ArunPiduguDD · claude · ArunPiduguDD · commit 6ba86830e103 · 2026-05-08T14:41:57.000-04:00
Replace the PerTagInner struct (with ambiguous optional fields) with a
PerTagConfig struct wrapping a PerTagMode tagged enum:

  - mode: limit_override + value_limit: N  — track with explicit cap
  - mode: excluded                          — opt out of tracking entirely

Removes PerTagInner, PerTagModeKind, and the old `excluded: bool` field.
The new shape is unambiguous: every per-tag entry must be one or the other.
YAML format is consistent with per-metric `mode: excluded`.

Co-Authored-By: Claude Opus 4.7 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/changelog.d/tag_cardinality_limit_per_tag_and_exclude.enhancement.md b/changelog.d/tag_cardinality_limit_per_tag_and_exclude.enhancement.md
@@ -1,20 +1,6 @@
 The `tag_cardinality_limit` transform gained two new configuration capabilities:
 
-- **Per-tag overrides**: each entry in `per_metric_limits` now supports a `per_tag_limits`
-  map whose entries can override settings for a specific tag key on that metric. The
-  following per-tag fields are available:
-  - `value_limit` (optional): caps distinct values for this tag key. Inherits from the
-    enclosing per-metric `value_limit` when unset.
-  - `excluded` (default `false`): when `true`, opts this tag out of cardinality tracking
-    entirely — all values pass through unchecked.
-
-  The tracking mode (`exact`/`probabilistic`), `cache_size_per_key`, `limit_exceeded_action`,
-  and `internal_metrics` are always inherited from the enclosing per-metric configuration
-  and cannot be overridden per-tag.
-
-- **Metric exclusion**: `mode: excluded` is now available in `per_metric_limits` entries
-  (not at the global level). When set, every tag on that metric is opted out of cardinality
-  control — all tag values pass through and nothing is tracked. Any `per_tag_limits`
-  overrides on an excluded metric are ignored.
+- **Per-tag overrides** (`per_tag_limits`): configure cardinality limits per tag key within a metric, or exclude individual tags from tracking.
+- **Metric exclusion**: opt entire metrics out of cardinality tracking via `mode: excluded` in `per_metric_limits`.
 
 authors: ArunPiduguDD
diff --git a/src/transforms/tag_cardinality_limit/config.rs b/src/transforms/tag_cardinality_limit/config.rs
@@ -129,12 +129,12 @@ pub struct PerMetricConfig {
     #[serde(default)]
     pub namespace: Option<String>,
 
-    /// Per-tag-key overrides scoped to this metric.
+    /// Per-tag-key overrides scoped to this metric. Each entry sets a `mode`:
+    /// - `mode: limit_override` + `value_limit: N` — track with a per-tag cap.
+    /// - `mode: excluded` — opt this tag out of tracking entirely.
     ///
-    /// Each entry may override `value_limit` for a specific tag key or opt it out of
-    /// tracking entirely with `excluded: true`. The tracking mode, `cache_size_per_key`,
-    /// `limit_exceeded_action`, and `internal_metrics` are always inherited from the
-    /// enclosing per-metric configuration and cannot be set per-tag.
+    ///  All other settings (tracking algorithm, `limit_exceeded_action`, etc.)
+    /// are inherited from the enclosing per-metric configuration.
     /// Tags not listed here use the per-metric configuration.
     #[configurable(
         derived,
@@ -185,12 +185,9 @@ pub enum OverrideMode {
     Probabilistic(BloomFilterConfig),
 
     /// Skip cardinality tracking for this metric. All tag values pass through and nothing is
-    /// recorded. Other tracking fields on the entry (`value_limit`, `limit_exceeded_action`,
+    /// limited. Other tracking fields on the entry (`value_limit`, `limit_exceeded_action`,
     /// `internal_metrics`) are ignored when this is selected. Any `per_tag_limits` entries
     /// on this metric are also ignored.
-    ///
-    /// Only valid in `per_metric_limits` entries; using it as the global `mode` is a
-    /// configuration error.
     Excluded,
 }
 
@@ -209,33 +206,46 @@ impl OverrideMode {
 // Per-tag configuration block
 // =============================================================================
 
-/// Tag cardinality limit configuration for a specific tag key, scoped under a per-metric override.
+/// Per-tag cardinality configuration.
+///
+/// Specify `mode` to control how this tag is handled:
+///
+/// Example:
+/// ```yaml
+/// per_tag_limits:
+///   environment:
+///     mode: limit_override  # track with a per-tag cap
+///     value_limit: 3
+///   trace_id:
+///     mode: excluded        # opt out of tracking entirely
+/// ```
 #[configurable_component]
 #[derive(Clone, Copy, Debug, Eq, PartialEq)]
 pub struct PerTagConfig {
+    #[configurable(derived)]
     #[serde(flatten)]
-    pub config: PerTagInner,
+    pub mode: PerTagMode,
 }
 
-/// Configuration block used at the per-tag level.
+/// Mode applied to a specific tag key within a per-metric override.
 ///
-/// The tracking mode (`exact` or `probabilistic`) and `cache_size_per_key` are always
-/// inherited from the enclosing per-metric configuration and cannot be overridden per-tag.
-/// A tag can be opted out of cardinality tracking entirely with `excluded: true`.
+/// The tracking algorithm (`exact`/`probabilistic`), `cache_size_per_key`,
+/// `limit_exceeded_action`, and `internal_metrics` are always inherited from the
+/// enclosing per-metric configuration regardless of the per-tag mode.
 #[configurable_component]
 #[derive(Clone, Copy, Debug, Eq, PartialEq)]
-pub struct PerTagInner {
-    /// How many distinct values to accept for this tag key. If unset, inherits
-    /// the `value_limit` from the enclosing per-metric (or global) configuration.
-    /// Ignored when `excluded: true`.
-    #[serde(default)]
-    pub value_limit: Option<usize>,
-
-    /// When `true`, opts this tag out of cardinality tracking entirely. All values
-    /// for this tag pass through without being recorded or checked against
-    /// `value_limit`. Defaults to `false`.
-    #[serde(default)]
-    pub excluded: bool,
+#[serde(tag = "mode", rename_all = "snake_case", deny_unknown_fields)]
+#[configurable(metadata(docs::enum_tag_description = "Controls how this tag key is handled."))]
+pub enum PerTagMode {
+    /// Track this tag with a per-tag value limit. The enclosing per-metric tracking
+    /// algorithm and all other settings still apply.
+    LimitOverride {
+        /// Maximum number of distinct values to accept for this tag key.
+        value_limit: usize,
+    },
+    /// Opt this tag out of cardinality tracking entirely. All values pass through
+    /// without being recorded or checked against any `value_limit`.
+    Excluded,
 }
 
 // =============================================================================
diff --git a/src/transforms/tag_cardinality_limit/mod.rs b/src/transforms/tag_cardinality_limit/mod.rs
@@ -17,8 +17,9 @@ mod tests;
 
 pub use config::{
     BloomFilterConfig, Config, Inner, LimitExceededAction, Mode, OverrideInner, OverrideMode,
-    PerMetricConfig, PerTagConfig, PerTagInner, TrackingScope,
+    PerMetricConfig, PerTagConfig, PerTagMode, TrackingScope,
 };
+
 use tag_value_set::AcceptedTagValueSet;
 
 use crate::event::metric::TagValueSet;
@@ -84,15 +85,14 @@ impl TagCardinalityLimit {
 
     /// Resolve the configuration that applies to a specific (metric, tag) pair.
     ///
-    /// Lookup chain (per field):
-    /// - `value_limit`: per-tag override → per-metric → global.
-    /// - `mode`, `cache_size_per_key`, `limit_exceeded_action`, `internal_metrics`:
-    ///   per-metric → global. These fields cannot be overridden per-tag.
+    /// Per-tag entries support two modes:
+    /// - `mode: limit_override` — uses the per-tag `value_limit`; all other settings
+    ///   (`mode`, `cache_size_per_key`, `limit_exceeded_action`, `internal_metrics`)
+    ///   are inherited from the per-metric config.
+    /// - `mode: excluded` — opts the tag out entirely; all values pass through.
     ///
-    /// Per-tag exclusion: if the per-tag entry has `excluded: true`, the tag is opted out
-    /// regardless of the enclosing per-metric settings.
-    /// Per-metric exclusion is blanket: if the per-metric entry has `mode: excluded`,
-    /// every tag on the metric is excluded and `per_tag_limits` is ignored.
+    /// Per-metric exclusion is blanket: `mode: excluded` on a per-metric entry opts out
+    /// every tag on that metric and `per_tag_limits` is ignored.
     fn get_config_for_metric_tag(
         &self,
         metric_key: Option<&MetricId>,
@@ -116,20 +116,22 @@ impl TagCardinalityLimit {
         let metric_value_limit = per_metric.config.value_limit;
         let internal_metrics = per_metric.config.internal_metrics;
 
-        // Per-tag entry may exclude the tag or override `value_limit`.
-        // All other fields (mode, cache_size_per_key, etc.) are always inherited
-        // from the per-metric configuration.
+        // Per-tag entry: LimitOverride uses an explicit value_limit; Excluded opts
+        // the tag out. All other settings are always inherited from per-metric.
         if let Some(per_tag) = per_metric.per_tag_limits.get(tag_key) {
-            if per_tag.config.excluded {
-                return TagSettings::Excluded;
+            match per_tag.mode {
+                PerTagMode::Excluded => return TagSettings::Excluded,
+                PerTagMode::LimitOverride { value_limit } => {
+                    // Tracking algorithm and all other settings are always inherited
+                    // from the per-metric config.
+                    return TagSettings::Tracked(Inner {
+                        value_limit,
+                        limit_exceeded_action,
+                        mode: metric_mode,
+                        internal_metrics,
+                    });
+                }
             }
-            // Mode and cache_size_per_key are always inherited from the per-metric config.
-            return TagSettings::Tracked(Inner {
-                value_limit: per_tag.config.value_limit.unwrap_or(metric_value_limit),
-                limit_exceeded_action,
-                mode: metric_mode,
-                internal_metrics,
-            });
         }
         TagSettings::Tracked(Inner {
             value_limit: metric_value_limit,
@@ -157,7 +159,7 @@ impl TagCardinalityLimit {
     ///
     /// Returns:
     /// - `Accepted` if the value is already tracked, fits under the configured
-    ///   `value_limit` and is now recorded, or the tag has `excluded: true`
+    ///   `value_limit` and is now recorded, or the per-tag entry is `mode: excluded`
     ///   (pass-through).
     /// - `Rejected` if the value would exceed `value_limit`; the caller should drop
     ///   the tag.
diff --git a/src/transforms/tag_cardinality_limit/tests.rs b/src/transforms/tag_cardinality_limit/tests.rs
@@ -765,10 +765,7 @@ fn max_tracked_keys_caps_across_per_metric_buckets() {
 
 fn make_per_tag(value_limit: usize) -> PerTagConfig {
     PerTagConfig {
-        config: PerTagInner {
-            value_limit: Some(value_limit),
-            excluded: false,
-        },
+        mode: PerTagMode::LimitOverride { value_limit },
     }
 }
 
@@ -804,10 +801,7 @@ fn make_per_metric_excluded(per_tag_limits: HashMap<String, PerTagConfig>) -> Pe
 
 fn make_per_tag_excluded() -> PerTagConfig {
     PerTagConfig {
-        config: PerTagInner {
-            value_limit: None,
-            excluded: true,
-        },
+        mode: PerTagMode::Excluded,
     }
 }
 
@@ -1044,80 +1038,67 @@ fn tag_excluded_unbounded_sibling_limited() {
     }
 }
 
-/// A per-tag entry with `value_limit` unset must inherit the per-metric `value_limit`
-/// rather than silently falling back to the serde default of 500.
+/// A per-tag `LimitOverride` entry caps that tag at its explicit `value_limit`,
+/// independent of the per-metric limit.
 #[test]
-fn per_tag_value_limit_inherits_from_per_metric() {
+fn per_tag_limit_override_caps_at_explicit_value() {
     let per_tag = PerTagConfig {
-        config: PerTagInner {
-            value_limit: None, // unset → should inherit from the per-metric (3)
-            excluded: false,
-        },
+        mode: PerTagMode::LimitOverride { value_limit: 2 },
     };
     let config = make_transform_hashset_with_per_metric_limits(
         500,
         LimitExceededAction::DropTag,
         HashMap::from([(
             "metricA".to_string(),
             make_per_metric(
-                3,
+                10,
                 LimitExceededAction::DropTag,
                 HashMap::from([("tag1".to_string(), per_tag)]),
             ),
         )]),
     );
     let mut transform = TagCardinalityLimit::new(config);
 
-    // First 3 distinct values for tag1 are accepted (inherits per-metric limit of 3).
-    for i in 0..3 {
-        let v = format!("v{i}");
+    // First 2 values pass (per-tag limit = 2).
+    for v in ["v0", "v1"] {
         let e = transform
-            .transform_one(make_metric_with_name(
-                metric_tags!("tag1" => v.clone()),
-                "metricA",
-            ))
+            .transform_one(make_metric_with_name(metric_tags!("tag1" => v), "metricA"))
             .unwrap();
-        assert_eq!(
-            v.as_str(),
-            e.as_metric().tags().unwrap().get("tag1").unwrap()
-        );
+        assert_eq!(v, e.as_metric().tags().unwrap().get("tag1").unwrap());
     }
 
-    // 4th value should be rejected — proves the per-tag entry did NOT silently widen
-    // the limit to 500.
-    let e4 = transform
+    // 3rd value dropped — proves the per-tag limit (2) applies, not the per-metric (10).
+    let e3 = transform
         .transform_one(make_metric_with_name(
-            metric_tags!("tag1" => "v3"),
+            metric_tags!("tag1" => "v2"),
             "metricA",
         ))
         .unwrap();
-    assert!(!e4.as_metric().tags().unwrap().contains_key("tag1"));
+    assert!(!e3.as_metric().tags().unwrap().contains_key("tag1"));
 }
 
-/// A per-tag entry like `{ value_limit: 10 }` must deserialize successfully.
+/// Per-tag YAML syntax: `mode: limit_override` with `value_limit`, and `mode: excluded`.
 #[test]
-fn per_tag_value_limit_only_deserializes() {
+fn per_tag_modes_deserialize() {
     let yaml = r#"
 value_limit: 5
 mode: exact
 per_metric_limits:
   metric_a:
     mode: exact
     per_tag_limits:
-      tag_only_value_limit:
+      capped_tag:
+        mode: limit_override
         value_limit: 10
       excluded_tag:
-        excluded: true
+        mode: excluded
 "#;
     let parsed: Config = serde_yaml::from_str(yaml).expect("yaml should deserialize");
     let per_metric = parsed.per_metric_limits.get("metric_a").unwrap();
-    let only_limit = per_metric
-        .per_tag_limits
-        .get("tag_only_value_limit")
-        .unwrap();
-    assert_eq!(only_limit.config.value_limit, Some(10));
-    assert!(!only_limit.config.excluded);
+
+    let capped = per_metric.per_tag_limits.get("capped_tag").unwrap();
+    assert_eq!(capped.mode, PerTagMode::LimitOverride { value_limit: 10 });
 
     let excluded = per_metric.per_tag_limits.get("excluded_tag").unwrap();
-    assert!(excluded.config.excluded);
+    assert_eq!(excluded.mode, PerTagMode::Excluded);
 }
diff --git a/website/cue/reference/components/transforms/generated/tag_cardinality_limit.cue b/website/cue/reference/components/transforms/generated/tag_cardinality_limit.cue
@@ -128,12 +128,10 @@ generated: components: transforms: tag_cardinality_limit: configuration: {
 					type: string: enum: {
 						exact: "Tracks cardinality exactly. See `Mode::Exact` for details."
 						excluded: """
-																			Skip cardinality tracking for this scope. All tag values pass through and nothing is
-																			recorded. Other tracking fields on the entry (`value_limit`, `limit_exceeded_action`,
-																			`internal_metrics`) are ignored when this is selected.
-
-																			Only valid in `per_metric_limits` and `per_tag_limits` entries; using it as the global
-																			`mode` is a configuration error.
+																			Skip cardinality tracking for this metric. All tag values pass through and nothing is
+																			limited. Other tracking fields on the entry (`value_limit`, `limit_exceeded_action`,
+																			`internal_metrics`) are ignored when this is selected. Any `per_tag_limits` entries
+																			on this metric are also ignored.
 																			"""
 						probabilistic: "Tracks cardinality probabilistically. See `Mode::Probabilistic` for details."
 					}
@@ -145,34 +143,37 @@ generated: components: transforms: tag_cardinality_limit: configuration: {
 				}
 				per_tag_limits: {
 					description: """
-						Per-tag-key overrides scoped to this metric.
+						Per-tag-key overrides scoped to this metric. Each entry sets a `mode`:
+						- `mode: limit_override` + `value_limit: N` — track with a per-tag cap.
+						- `mode: excluded` — opt this tag out of tracking entirely.
 
-						Each entry may override `value_limit` and `mode` for a specific tag key.
-						`limit_exceeded_action` and `internal_metrics` are always inherited from the enclosing
-						per-metric (or global) configuration and cannot be set per-tag.
+						All other settings (tracking algorithm, `limit_exceeded_action`, etc.)
+						are inherited from the enclosing per-metric configuration.
 						Tags not listed here use the per-metric configuration.
 						"""
 					required: false
 					type: object: options: "*": {
 						description: "An individual tag configuration."
 						required:    true
 						type: object: options: {
-							excluded: {
-								description: """
-																								When `true`, opts this tag out of cardinality tracking entirely. All values
-																								for this tag pass through without being recorded or checked against
-																								`value_limit`. Defaults to `false`.
-																								"""
-								required: false
-								type: bool: default: false
+							mode: {
+								description: "Controls how this tag key is handled."
+								required:    true
+								type: string: enum: {
+									excluded: """
+																											Opt this tag out of cardinality tracking entirely. All values pass through
+																											without being recorded or checked against any `value_limit`.
+																											"""
+									limit_override: """
+																											Track this tag with a per-tag value limit. The enclosing per-metric tracking
+																											algorithm and all other settings still apply.
+																											"""
+								}
 							}
 							value_limit: {
-								description: """
-																								How many distinct values to accept for this tag key. If unset, inherits
-																								the `value_limit` from the enclosing per-metric (or global) configuration.
-																								Ignored when `excluded: true`.
-																								"""
-								required: false
+								description:   "Maximum number of distinct values to accept for this tag key."
+								relevant_when: "mode = \"limit_override\""
+								required:      true
 								type: uint: {}
 							}
 						}
