​

Cardinalityguardian Processor

​

Supported Telemetry

​

Overview

​

What it does

Before:  {region="us-east", status="200", error.type="Lock wait timeout; txn=a3f9c..."}
After:   {region="us-east", status="200"}

​

How it works

• Delta-based detection, not absolute thresholds. A label with 50K stable values is fine. A label that grew by 100 in the last epoch is a problem. The processor tracks growth rate using dual-epoch HyperLogLog++ sketches, so legitimate high-cardinality metrics aren’t penalized.
• 256-way sharding. Each shard has its own RWMutex. With 50 concurrent goroutines across 256 shards, average occupancy is ~0.4 per shard. Contention is near zero. Shard selection is hash & 0xFF — one CPU cycle.
• HLL++ with ~2KB per tracker. Each sketch estimates cardinality regardless of whether 100 or 100M unique values have been observed. 1-2% accuracy. The axiomhq/hyperloglog library’s InsertHash(uint64) path avoids allocation on the hot path.
• Stale eviction. Trackers that haven’t been seen for two epochs are cleaned up. Memory stays bounded.

​

Comparison with existing processors

​

Configuration

processors:
  cardinality_guardian:
    # Max new unique values per (metric, attribute) per epoch
    max_cardinality_delta_per_epoch: 100

    # Epoch rotation interval (seconds, minimum 10)
    epoch_duration_seconds: 300

    # Enforcement mode: tag_only | overflow_attribute | strip_and_reaggregate
    enforcement_mode: tag_only

    # Labels that are never stripped regardless of cardinality
    never_drop_labels:
      - region
      - environment
      - service.name

    # Per-metric threshold overrides (falls back to global if unset)
    metric_overrides:
      http.server.request.duration: 5000
      db.query.duration: 50

    # Emit gauge with top N highest-delta trackers
    top_offenders_count: 10

    # Max tracked metric+label pairs (0 = unlimited)
    max_tracker_count: 100000

    # Dollar value per series prevented, for ROI dashboards
    estimated_cost_per_metric_month: 0.05

    # Cap enforcement Warn logs per epoch (0 = unlimited)
    drop_log_max_per_epoch: 10

​

Enforcement Modes

​

Tag Only

enforcement_mode: tag_only

Note: tag_only does not protect your TSDB on its own — high-cardinality labels still reach your backend unchanged. You must pair it with a downstream routing processor to split tagged metrics to cheap storage.

​

Overflow Attribute

enforcement_mode: overflow_attribute

​

Strip and Reaggregate

enforcement_mode: strip_and_reaggregate

Note: For metric types that don’t yet support reaggregation, the processor automatically falls back to tag_only behavior with an otel.metric.overflow tag, ensuring no data corruption.

​

Warnings

• Single-Writer Conflict: strip_and_reaggregate and overflow_attribute both intentionally cause attribute identity collisions and rely on inline spatial reaggregation to merge them. Reaggregation is only safe for Delta Sums and Gauges; Cumulative Sums, Histograms, ExponentialHistograms, and Summaries require stateful tracking that this processor doesn’t perform, so they fall back to tag_only regardless of the configured mode. overflow_attribute is not a valid fallback for those types — collapsing multiple cumulative streams (or merging histogram buckets across mis-aligned scales) is what reaggregation has to solve in the first place.
• Hash Collisions: Identity hashing uses xxhash with per-pcommon.ValueType dispatch and a multiplicative key/value mix to remain order-independent. Theoretical hash collisions are possible but vanishingly rare for typical attribute maps.
• Future work: Supporting reaggregation across multiple OTel SDK strategies (metrics SDK aggregation) — e.g. Cumulative Sum reaggregation with stateful tracking, Histogram bucket-aligned merging — is out of scope for this PR but tracked as a follow-up.

​

Troubleshooting