OpenTelemetry W3C Baggage PII Sanitization and Cardinality Control

--- description: OpenTelemetry W3C Baggage PII Sanitization and Cardinality Control - Enforces strict payload boundaries, cryptographic hashing of contextual identifiers, and automated PII scrubbing on OpenTelemetry W3C Baggage headers across microservice hops. Baggage is propagated downstream across trust boundaries in cleartext HTTP headers, making raw PII propagation and unbounded cardinality critical security vulnerabilities and DoS attack vectors. globs: src/telemetry/**/*.{ts,js,py,go,java}, src/middleware/**/*.{ts,js,py,go,java}, src/instrumentation/**/*.{ts,js,py,go,java}, src/tracing/**/*.{ts,js,py,go,java} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/opentelemetry-baggage-pii-cardinality-guardrail" --- # OpenTelemetry W3C Baggage PII Sanitization and Cardinality Control > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: Propagating Unsanitized PII and Unbounded Dynamic Metadata in W3C Baggage Headers ## System Constraints You are a Principal Software Architect enforcing zero-trust observability. OpenTelemetry Baggage traverses transport boundaries unchecked by default; you must mandate strict allowlists, HMAC tokenization for subject IDs, total byte-size enforcement (max 8192 bytes total, max 64 key-value pairs per W3C specification), and automatic dropping of prohibited metadata. ## Strict Guidelines - Engineers MUST ALWAYS enforce an explicit allowlist of permitted baggage keys; dynamic or arbitrary key injection is strictly forbidden. - Engineers MUST NEVER propagate raw PII (emails, phone numbers, IP addresses, full legal names, SSNs) or authentication secrets (bearer tokens, API keys) inside W3C Baggage headers. - Services MUST cryptographically hash or pseudonymize customer or tenant identifiers using HMAC-SHA256 with an ephemeral or rotating salt before appending them to Baggage. - Middleware MUST enforce strict W3C Baggage size limits: reject or truncate total baggage header size exceeding 8,192 bytes, individual member length exceeding 4,096 bytes, or pair counts exceeding 64 entries. - Custom baggage propagators MUST validate and sanitize input characters to strictly adhere to RFC 7230 token requirements, stripping CRLF or header-injection vectors before propagation. - Outbound HTTP clients MUST strip internal-only baggage items when crossing public network perimeters or communicating with external third-party APIs. ## Bad vs Good Implementations ### Unsanitized Direct Baggage Injection vs. Guardrailed Baggage Sanitizer Middleware #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Directly stores raw PII (email), authorization bearer tokens, and unbounded arbitrary JSON payloads into baggage. This leaks sensitive data downstream through headers, exposes credentials to downstream third-party logs, and triggers HTTP 431/502 errors due to uncontrolled header bloat. ```typescript import { propagation, context } from '@opentelemetry/api'; import { Request, Response, NextFunction } from 'express'; export function telemetryMiddleware(req: Request, res: Response, next: NextFunction): void { // ANTI-PATTERN: Blindly attaching unsanitized request headers and raw customer PII // Baggage header size can exceed proxy limits (413/502) and leaks PII downstream let currentBaggage = propagation.getBaggage(context.active()) || propagation.createBaggage(); currentBaggage = currentBaggage.setEntry('user.email', { value: req.body.email }); currentBaggage = currentBaggage.setEntry('user.auth_token', { value: req.headers['authorization'] || '' }); currentBaggage = currentBaggage.setEntry('request.payload', { value: JSON.stringify(req.body) }); const newContext = propagation.setBaggage(context.active(), currentBaggage); context.with(newContext, () => next()); } ``` #### Production Standard (Correct) > **Standard**: Enforces an allowlist of permitted keys, truncates and validates individual entries against RFC character constraints, enforces total size and entry limits, and hashes tenant identifiers via HMAC-SHA256 to guarantee zero raw PII is propagated across network hops. ```typescript import { propagation, context, Baggage, BaggageEntry } from '@opentelemetry/api'; import { Request, Response, NextFunction } from 'express'; import { createHmac } from 'crypto'; const MAX_BAGGAGE_BYTES = 8192; const MAX_ENTRIES = 32; const ALLOWED_KEYS = new Set(['tenant.id_hash', 'region', 'client.env', 'feature_flags']); const HMAC_SALT = process.env.TELEMETRY_PSEUDONYMIZATION_KEY || 'default-static-fallback-key'; function hashIdentifier(rawId: string): string { return createHmac('sha256', HMAC_SALT).update(rawId).digest('hex').slice(0, 16); } export function sanitizedBaggageMiddleware(req: Request, res: Response, next: NextFunction): void { const existingBaggage = propagation.getBaggage(context.active()) || propagation.createBaggage(); let sanitizedBaggage = propagation.createBaggage(); let totalBytes = 0; let entryCount = 0; const addSafeEntry = (key: string, value: string): void => { if (!ALLOWED_KEYS.has(key) || entryCount >= MAX_ENTRIES) return; const sanitizedValue = value.replace(/[^a-zA-Z0-9_.-]/g, '_'); const entryByteCost = Buffer.byteLength(`${key}=${sanitizedValue}`); if (totalBytes + entryByteCost > MAX_BAGGAGE_BYTES) return; sanitizedBaggage = sanitizedBaggage.setEntry(key, { value: sanitizedValue }); totalBytes += entryByteCost; entryCount++; }; // Copy existing baggage only if keys are allowlisted for (const [key, entry] of existingBaggage.getAllEntries()) { addSafeEntry(key, entry.value); } // Inject pseudonymized contextual markers if (req.headers['x-tenant-id']) { const rawTenant = Array.isArray(req.headers['x-tenant-id']) ? req.headers['x-tenant-id'][0] : req.headers['x-tenant-id']; addSafeEntry('tenant.id_hash', hashIdentifier(rawTenant)); } if (process.env.APP_REGION) { addSafeEntry('region', process.env.APP_REGION); } const newContext = propagation.setBaggage(context.active(), sanitizedBaggage); context.with(newContext, () => next()); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: OpenTelemetry W3C Baggage PII Sanitization and Cardinality Control

OpenTelemetry W3C Baggage PII Sanitization and Cardinality Control defines an industrial-grade behavioral standard for devops engineering. Enforces strict payload boundaries, cryptographic hashing of contextual identifiers, and automated PII scrubbing on OpenTelemetry W3C Baggage headers across microservice hops. Baggage is propagated downstream across trust boundaries in cleartext HTTP headers, making raw PII propagation and unbounded cardinality critical security vulnerabilities and DoS attack vectors. 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: Propagating Unsanitized PII and Unbounded Dynamic Metadata in W3C Baggage Headers 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	Propagating Unsanitized PII and Unbounded Dynamic Metadata in W3C Baggage Headers	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 enforce an explicit allowlist of permitted baggage keys

Engineers MUST ALWAYS enforce an explicit allowlist of permitted baggage keys; dynamic or arbitrary key injection is strictly forbidden.

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.