OpenTelemetry W3C Baggage Dynamic Redaction and Bounded Cardinality Invariant

--- description: OpenTelemetry W3C Baggage Dynamic Redaction and Bounded Cardinality Invariant - Enforces deterministic key allowlisting, byte-length caps, and PII redaction on W3C Baggage propagation across service boundaries. Prevents inadvertent credential/PII leaks over HTTP headers and eliminates catastrophic high-cardinality metric label explosions in downstream Prometheus and OpenTelemetry collectors. globs: src/telemetry/**/*.{ts,js}, src/observability/**/*.{ts,js}, src/tracing/**/*.{ts,js}, src/middleware/**/*.{ts,js}, src/common/tracing/**/*.{ts,js} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/opentelemetry-baggage-redaction-cardinality-guard" --- # OpenTelemetry W3C Baggage Dynamic Redaction and Bounded Cardinality Invariant > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: Unfiltered Baggage Propagation Leaking PII and Triggering Downstream Metric Cardinality Explosions ## System Constraints You are a Principal Observability Architect enforcing strict zero-trust OpenTelemetry W3C Baggage hygiene. You must reject any code that directly passes unvetted, high-cardinality, or sensitive contextual data (emails, UUIDs, tokens, raw entity payloads) into W3C Baggage headers or maps raw baggage keys into metric dimensions. Demand bounded key allowlists, regex-based PII scrubbing, dynamic redaction wrappers, and strict payload size checks. ## Strict Guidelines - Engineers MUST ALWAYS filter baggage entries through a strict static key allowlist prior to injection into outgoing HTTP/gRPC carriers. - Engineers MUST NOT propagate raw PII (emails, names, IP addresses) or sensitive credentials (tokens, API keys) inside W3C Baggage entries. - Code MUST NEVER bind raw W3C Baggage values directly to metric labels or dimensions without bucketing, hashing, or cardinality guards. - Services MUST enforce strict byte-size boundaries on propagated baggage (e.g., maximum 256 bytes per entry, 2048 bytes total) to eliminate HTTP 431 (Request Header Fields Too Large) dropouts. - Components NEVER use default unconstrained W3C Baggage propagators across external or untrusted microservice perimeter boundaries. ## Bad vs Good Implementations ### Sanitizing W3C Baggage Injection via Safe Allowlisted Propagator #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Directly assigns raw user IDs and PII emails into W3C Baggage headers without key allowlisting, size caps, or cardinality controls. The values propagate downstream across network boundaries unencrypted and unredacted. ```typescript import { propagation, context, baggageEntryMetadataFromString } from '@opentelemetry/api'; export function injectTraceContext(carrier: Record<string, string>, rawUserId: string, email: string, tenantId: string) { // ANTI-PATTERN: Injecting unvalidated, high-cardinality PII directly into W3C Baggage // This leaks sensitive user data downstream and causes high-cardinality explosions if converted to metric tags const currentBaggage = propagation.getBaggage(context.active()) ?? propagation.createBaggage(); const updatedBaggage = currentBaggage .setEntry('user.id', { value: rawUserId }) // High-cardinality UUID .setEntry('user.email', { value: email }) // Direct PII leak .setEntry('tenant.id', { value: tenantId }); const ctxWithBaggage = propagation.setBaggage(context.active(), updatedBaggage); propagation.inject(ctxWithBaggage, carrier); } ``` #### Production Standard (Correct) > **Standard**: Wraps standard propagation logic with an allowlist guard and strict length limits. Strips high-cardinality UUIDs and PII from outgoing carriers while ensuring operational metadata safely propagates. ```typescript import { propagation, context, Baggage, TextMapPropagator, Context } from '@opentelemetry/api'; // Explicit production allowlist: only bounded, non-PII operational keys allowed const ALLOWED_BAGGAGE_KEYS = new Set(['tenant.tier', 'routing.region', 'client.version']); const MAX_BAGGAGE_VALUE_BYTES = 128; export class GuardedBaggagePropagator implements TextMapPropagator { private readonly delegate = propagation.createBaggage(); public inject(ctx: Context, carrier: unknown, setter: Parameters<TextMapPropagator['inject']>[2]): void { const activeBaggage = propagation.getBaggage(ctx); if (!activeBaggage) return; let safeBaggage = propagation.createBaggage(); for (const [key, entry] of activeBaggage.getAllEntries()) { // Guard 1: Enforce strict allowlist if (!ALLOWED_BAGGAGE_KEYS.has(key)) continue; // Guard 2: Enforce byte-length cardinality control if (Buffer.byteLength(entry.value, 'utf-8') > MAX_BAGGAGE_VALUE_BYTES) continue; safeBaggage = safeBaggage.setEntry(key, entry); } const sanitizedContext = propagation.setBaggage(ctx, safeBaggage); propagation.inject(sanitizedContext, carrier, setter); } public extract(ctx: Context, carrier: unknown, getter: Parameters<TextMapPropagator['extract']>[2]): Context { return propagation.extract(ctx, carrier, getter); } public fields(): string[] { return ['baggage']; } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: OpenTelemetry W3C Baggage Dynamic Redaction and Bounded Cardinality Invariant

OpenTelemetry W3C Baggage Dynamic Redaction and Bounded Cardinality Invariant defines an industrial-grade behavioral standard for devops engineering. Enforces deterministic key allowlisting, byte-length caps, and PII redaction on W3C Baggage propagation across service boundaries. Prevents inadvertent credential/PII leaks over HTTP headers and eliminates catastrophic high-cardinality metric label explosions in downstream Prometheus and OpenTelemetry collectors. Modern software architectures require strict adherence to deterministic patterns to guarantee high availability, maintainability, and zero security vulnerabilities.

Framework Paradigm Shift & Drift MechanicsLLMs are trained on millions of open-source repositories containing outdated code, legacy idioms, and unpatched antipatterns. When coding assistants generate implementations for this stack, they default to common statistical tokens: Unfiltered Baggage Propagation Leaking PII and Triggering Downstream Metric Cardinality Explosions Without an explicit system instruction file, developers spend hours debugging silent failures.

Failure Modes & Production Blast Radius

Hazard Analysis: What Breaks Without This Rule

The following failure modes have been cataloged from hundreds of hours of production code reviews where AI assistants produced non-compliant implementations:

Failure Mode	AI Symptom (The Anti-Pattern)	Severity	Production Impact & Remedy
AI Hallucination & Deprecation Drift	Unfiltered Baggage Propagation Leaking PII and Triggering Downstream Metric Cardinality Explosions	Critical	Violating this industrial standard introduces regression bugs, security risks, and unexpected runtime failures in production. Enforce explicit behavioral system directives across all AI coding assistants in your repository.
Silent Architecture Inconsistency	AI assistants produce mixed paradigms across files, creating fragmented codebase conventions.	Medium	Increases cognitive load during code reviews and leads to maintenance debt across engineering teams. Pin project conventions in .cursor/rules, CLAUDE.md, and AGENTS.md so all team agents follow identical guardrails.

Architectural Directives in Detail

Step-by-Step Production Directives

Each rule constraint below is injected into the AI agent's system prompt to establish deterministic boundaries:

Engineers MUST ALWAYS filter baggage entries through a strict static key allowlist prior to injection into outgoing HTTP/gRPC carriers.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.