OpenTelemetry Baggage PII Redaction & Byte-Budget Envelope Standard

--- description: OpenTelemetry Baggage PII Redaction & Byte-Budget Envelope Standard - Enforces strict payload byte-budget caps and automated PII/credential sanitization on OpenTelemetry W3C Baggage entries. Unrestricted baggage propagation induces downstream HTTP 431 Request Header Fields Too Large outages via header amplification and leaks sensitive data across service trust boundaries. globs: src/**/*.{ts,tsx,js,mjs}, lib/**/*.{ts,js}, packages/**/*.{ts,js} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/opentelemetry-baggage-pii-redaction-envelope-guardrail" --- # OpenTelemetry Baggage PII Redaction & Byte-Budget Envelope Standard > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Unbounded and Unredacted OpenTelemetry Baggage Header Propagation Across Network Boundaries ## System Constraints You are a Principal Security and Observability Architect enforcing OpenTelemetry Baggage standards. You must strictly forbid raw, unvalidated, or unmetered baggage propagation. Mandate deterministic PII scrubbing, strict key allowlisting, and cumulative byte-budget enforcement before baggage injection into context. ## Strict Guidelines - Engineers MUST ALWAYS enforce a cumulative byte-budget ceiling (maximum 4096 bytes across all baggage entries) to prevent downstream proxy HTTP 431 header amplification failures. - Engineers MUST NOT inject high-entropy credentials, bearer tokens, API keys, passwords, or PII (e.g., emails, SSNs, phone numbers) into OpenTelemetry Baggage. - Code MUST apply deterministic regex redaction patterns against all Baggage values prior to calling propagation setters. - Services MUST validate baggage keys against an explicit runtime allowlist; arbitrary or unbounded user-supplied keys are strictly prohibited. - Components NEVER attach high-cardinality unbounded payloads (such as raw request/response bodies or query parameters) to OpenTelemetry Baggage. - Context injection MUST drop or truncate oversized baggage entries with diagnostic telemetry warnings rather than failing user requests silently or propagating oversized headers. ## Bad vs Good Implementations ### Unsanitized Baggage Injection vs. Byte-Budgeted Sanitized Baggage Envelope #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Directly injects sensitive PII (email) and credentials (auth.token) into W3C baggage headers without length checks or redaction. Downstream microservices, ingress proxies, and external API gateways will receive plain-text secrets and risk header amplification failures. ```typescript import { propagation, context } from '@opentelemetry/api'; export function attachContextData(req: { user: { id: string; email: string; token: string } }): void { // ANTI-PATTERN: Direct injection of raw PII and bearer tokens into baggage // No byte-budget check; causes HTTP 431 and cross-service credential leakage let baggage = propagation.getBaggage(context.active()) || propagation.createBaggage(); baggage = baggage.setEntry('user.id', { value: req.user.id }); baggage = baggage.setEntry('user.email', { value: req.user.email }); baggage = baggage.setEntry('auth.token', { value: req.user.token }); propagation.setBaggage(context.active(), baggage); } ``` #### Production Standard (Correct) > **Standard**: Implements an explicit key allowlist, strips credentials and PII via regex sanitizers, URI-encodes values safely, and checks cumulative header size against a 4096-byte ceiling to prevent header amplification. ```typescript import { propagation, context, Baggage, BaggageEntry } from '@opentelemetry/api'; const MAX_BAGGAGE_BYTES = 4096; const ALLOWED_BAGGAGE_KEYS = new Set(['tenant.id', 'user.id', 'client.version']); 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 sanitizeBaggageValue(val: string): string { let sanitized = val; for (const pattern of PII_PATTERNS) { sanitized = sanitized.replace(pattern, '[REDACTED]'); } return encodeURIComponent(sanitized); } export function setSafeBaggageEntry( currentCtx = context.active(), key: string, rawValue: string ): void { if (!ALLOWED_BAGGAGE_KEYS.has(key)) { return; } const sanitizedValue = sanitizeBaggageValue(rawValue); const activeBaggage = propagation.getBaggage(currentCtx) || propagation.createBaggage(); let cumulativeSize = 0; for (const [k, entry] of activeBaggage.getAllEntries()) { if (k !== key) { cumulativeSize += k.length + entry.value.length + 1; } } const entrySize = key.length + sanitizedValue.length + 1; if (cumulativeSize + entrySize > MAX_BAGGAGE_BYTES) { return; } const updatedBaggage = activeBaggage.setEntry(key, { value: sanitizedValue }); propagation.setBaggage(currentCtx, updatedBaggage); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: OpenTelemetry Baggage PII Redaction & Byte-Budget Envelope Standard

OpenTelemetry Baggage PII Redaction & Byte-Budget Envelope Standard defines an industrial-grade behavioral standard for security engineering. Enforces strict payload byte-budget caps and automated PII/credential sanitization on OpenTelemetry W3C Baggage entries. Unrestricted baggage propagation induces downstream HTTP 431 Request Header Fields Too Large outages via header amplification and leaks sensitive data across service trust boundaries. 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 Unredacted OpenTelemetry Baggage Header Propagation Across Network Boundaries 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 Unredacted OpenTelemetry Baggage Header Propagation Across Network Boundaries	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 a cumulative byte-budget ceiling (maximum 4096 bytes across all baggage entries) to prevent downstream proxy HTTP 431 header amplification failures.

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.