OpenTelemetry W3C Baggage Header Boundary and PII Redaction Invariant

--- description: OpenTelemetry W3C Baggage Header Boundary and PII Redaction Invariant - Enforces strict byte-quota limits and automated regex-driven PII redaction on OpenTelemetry W3C Baggage propagation. Prevents HTTP 431 header amplification denial-of-service vectors and downstream compliance violations caused by in-band context leakage. globs: src/telemetry/**/*.{ts,js}, src/tracing/**/*.{ts,js}, src/middleware/**/*.{ts,js}, src/instrumentation/**/*.{ts,js} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/opentelemetry-baggage-boundary-pii-redaction" --- # OpenTelemetry W3C Baggage Header Boundary and PII Redaction Invariant > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: Unbounded and Unsanitized Baggage Propagation Causing Header Flooding and PII Leakage ## System Constraints You are a Principal Observability and Security Architect enforcing strict W3C Baggage header governance across all distributed services. Unbounded or unsanitized OpenTelemetry baggage entries lead directly to cascading HTTP 431 (Request Header Fields Too Large) outages and severe regulatory penalties via cross-boundary PII transmission. You must mandate strict byte quotas, key whitelisting, and automated value redaction across all baggage propagation layers. ## Strict Guidelines - Engineers MUST ALWAYS enforce strict per-entry size limits (max 256 bytes) and aggregate baggage limits (max 2048 bytes) to prevent HTTP 431 request header amplification attacks. - Engineers MUST NEVER propagate sensitive personal data (PII) such as emails, bearer tokens, passwords, credit card numbers, or social security numbers inside W3C Baggage. - Code MUST wrap custom OpenTelemetry TextMapPropagator implementations with an automated sanitizer that scrubs unapproved keys and masks high-entropy/PII-matching values before injection. - Services MUST maintain an explicit key allowlist for injected baggage entries; arbitrary application-level key propagation is strictly prohibited. - Components NEVER blindly copy request headers directly into outgoing trace context baggage without validation and schema enforcement. ## Bad vs Good Implementations ### Naive Baggage Injection vs. Guarded Propagator with Byte Quotas and PII Redaction #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Directly injects arbitrary user payload data and sensitive identifiers into baggage without byte boundaries or content sanitization. This breaches W3C baggage size constraints, causes downstream proxy drops via HTTP 431, and introduces GDPR/SOC2 compliance violations. ```typescript import { propagation, context, ROOT_CONTEXT } from '@opentelemetry/api'; export function forwardTracingContext(req: any, targetHeaders: Record<string, string>) { // Anti-pattern: Injects arbitrary, unvalidated user data into baggage. // Can exceed ingress proxy header size limits (causing HTTP 431) // and leaks customer PII (e.g., email, session token) across distributed hops. let currentBaggage = propagation.getBaggage(context.active()) || propagation.createBaggage(); currentBaggage = currentBaggage.setEntry('user.email', { value: req.user.email }); currentBaggage = currentBaggage.setEntry('session.token', { value: req.headers['authorization'] || '' }); currentBaggage = currentBaggage.setEntry('request.payload', { value: JSON.stringify(req.body) }); const activeWithBaggage = propagation.setBaggage(context.active(), currentBaggage); propagation.inject(activeWithBaggage, targetHeaders); } ``` #### Production Standard (Correct) > **Standard**: Implements an explicit key allowlist, truncates individual entry lengths, strips known PII patterns via regex masking, and guarantees the total propagated baggage does not exceed the aggregate byte budget. ```typescript import { propagation, context, Baggage, BaggageEntry } from '@opentelemetry/api'; const MAX_AGGREGATE_BAGGAGE_BYTES = 2048; const MAX_ENTRY_VALUE_BYTES = 256; const ALLOWED_BAGGAGE_KEYS = new Set(['tenant.id', 'client.version', 'environment', 'feature.flags']); const PII_PATTERNS = [ /[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/g, // Email /bearer\s+[a-zA-Z0-9._~+/-]+=*/gi, // Bearer token /\b\d{3}-\d{2}-\d{4}\b/g // SSN ]; function sanitizeValue(value: string): string { let sanitized = value.slice(0, MAX_ENTRY_VALUE_BYTES); for (const pattern of PII_PATTERNS) { sanitized = sanitized.replace(pattern, '[REDACTED]'); } return encodeURIComponent(sanitized); } export function setGuardedBaggage( currentBaggage: Baggage, key: string, value: string ): Baggage { if (!ALLOWED_BAGGAGE_KEYS.has(key)) { return currentBaggage; // Drop disallowed keys silently or log via debug telemetry } const cleanValue = sanitizeValue(value); const projectedEntry: BaggageEntry = { value: cleanValue }; // Calculate aggregate byte footprint let totalBytes = key.length + cleanValue.length; for (const [k, v] of currentBaggage.getAllEntries()) { if (k !== key) { totalBytes += k.length + v.value.length; } } if (totalBytes > MAX_AGGREGATE_BAGGAGE_BYTES) { return currentBaggage; // Abort injection to preserve header boundary budget } return currentBaggage.setEntry(key, projectedEntry); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: OpenTelemetry W3C Baggage Header Boundary and PII Redaction Invariant

OpenTelemetry W3C Baggage Header Boundary and PII Redaction Invariant defines an industrial-grade behavioral standard for devops engineering. Enforces strict byte-quota limits and automated regex-driven PII redaction on OpenTelemetry W3C Baggage propagation. Prevents HTTP 431 header amplification denial-of-service vectors and downstream compliance violations caused by in-band context leakage. 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: Unbounded and Unsanitized Baggage Propagation Causing Header Flooding and PII Leakage 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	Unbounded and Unsanitized Baggage Propagation Causing Header Flooding and PII Leakage	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 strict per-entry size limits (max 256 bytes) and aggregate baggage limits (max 2048 bytes) to prevent HTTP 431 request header amplification attacks.

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.