OpenTelemetry Baggage Context Boundary & In-Flight PII Redaction Policy

--- description: OpenTelemetry Baggage Context Boundary & In-Flight PII Redaction Policy - Enforces strict allowlists and automatic redaction boundaries on OpenTelemetry W3C Baggage propagation across distributed systems. Prohibits direct injection of raw Personally Identifiable Information (PII), unmasked account tokens, or internal multi-tenant credentials into cross-service headers. Requires cryptographic pseudonymization or gateway stripping before headers traverse trust boundaries. globs: src/**/telemetry/**/*.{ts,js,py,go}, src/**/tracing/**/*.{ts,js,py,go}, src/**/middleware/**/*.{ts,js,py,go}, src/**/instrumentation/**/*.{ts,js,py,go} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/opentelemetry-baggage-trace-context-redaction" --- # OpenTelemetry Baggage Context Boundary & In-Flight PII Redaction Policy > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: Propagating Raw PII and Multi-Tenant Isolation Secrets Across Services via Unrestricted W3C Baggage Headers ## System Constraints You are a Principal Software Architect and Rules Author for AI Coding Agents enforcing distributed telemetry security. You must ensure that OpenTelemetry W3C Baggage (`baggage` HTTP header) never carries plaintext PII, sensitive user attributes, or raw multi-tenant tenant isolation tokens across network boundaries. Mandate allowlist-driven baggage filters, context-propagation wrappers, and trace-state hygiene across all microservice boundaries. ## Strict Guidelines - Engineers MUST ALWAYS enforce an explicit schema allowlist for keys propagated through OpenTelemetry Baggage (e.g., `request.id`, `routing.region`, `release.version`). - Engineers MUST NOT inject raw PII (such as `user.email`, `user.name`, `user.ip`, `ssn`) or authentication tokens (JWTs, session IDs, API keys) into Baggage context. - Services MUST pseudonymize tenant and entity identifiers using keyed HMAC or opaque surrogate UUIDs before serializing them into downstream trace baggage. - Outbound HTTP/gRPC transport interceptors MUST strip or sanitize unrecognized baggage keys before forwarding requests to external third-party endpoints or untrusted network zones. - Span attributes SHOULD be preferred over distributed baggage when metadata is only required for local telemetry analysis within a single service runtime boundary. - Baggage injection points MUST validate value lengths and total header size against the W3C Baggage limit (8192 bytes total, 4096 bytes per entry) to prevent request smuggling or header amplification attacks. ## Bad vs Good Implementations ### Unrestricted Direct Baggage Injection vs Schema-Filtered Baggage Sanitization #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Directly sets raw email addresses, internal multi-tenant slugs, and authentication bearer tokens into baggage. Baggage is injected into standard outbound HTTP headers ('baggage') and will propagate across all downstream microservices and external APIs, triggering compliance violations (GDPR/HIPAA/SOC2) and credential leakage. ```typescript import { context, propagation, trace } from '@opentelemetry/api'; import { Request, Response, NextFunction } from 'express'; export function telemetryContextMiddleware(req: Request, res: Response, next: NextFunction) { const user = req.user; // CRITICAL: Raw PII, internal tenant keys, and email are placed directly into W3C baggage. // This leaks plaintext user identities into downstream microservices, access logs, and 3rd-party SaaS traces. const baggage = propagation.createBaggage({ 'user.email': { value: user.email }, 'user.id': { value: user.id }, 'tenant.internal_db_slug': { value: req.headers['x-tenant-slug'] as string }, 'auth.bearer_token': { value: req.headers.authorization || '' } }); const activeContext = propagation.setBaggage(context.active(), baggage); context.with(activeContext, () => { next(); }); } ``` #### Production Standard (Correct) > **Standard**: Implements an explicit key allowlist, pseudonymizes multi-tenant identifiers using HMAC hashing, eliminates all raw PII and bearer tokens, and validates maximum entry lengths before context propagation. ```typescript import { context, propagation, Baggage, BaggageEntry } from '@opentelemetry/api'; import { Request, Response, NextFunction } from 'express'; import { createHmac } from 'crypto'; // Strict production allowlist of keys permitted in distributed baggage context const ALLOWED_BAGGAGE_KEYS = new Set<string>([ 'tenant.pseudonym', 'traffic.env', 'routing.cell' ]); function pseudonymizeTenantId(tenantId: string, salt: string): string { return createHmac('sha256', salt).update(tenantId).digest('hex').substring(0, 16); } export function telemetryContextMiddleware(req: Request, res: Response, next: NextFunction) { const rawTenant = (req.headers['x-tenant-id'] as string) ?? 'anonymous'; const tenantPseudonym = pseudonymizeTenantId(rawTenant, process.env.HMAC_SALT || 'telemetry-salt'); const proposedBaggage: Record<string, BaggageEntry> = { 'tenant.pseudonym': { value: tenantPseudonym }, 'traffic.env': { value: process.env.NODE_ENV ?? 'development' }, 'routing.cell': { value: process.env.DEPLOYMENT_CELL ?? 'cell-primary' } }; // Filter entries through strict allowlist and apply size guards const sanitizedBaggage = Object.entries(proposedBaggage).reduce((bag, [key, entry]) => { if (ALLOWED_BAGGAGE_KEYS.has(key) && entry.value.length <= 256) { return bag.setEntry(key, entry); } return bag; }, propagation.createBaggage()); const activeContext = propagation.setBaggage(context.active(), sanitizedBaggage); context.with(activeContext, () => { next(); }); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: OpenTelemetry Baggage Context Boundary & In-Flight PII Redaction Policy

OpenTelemetry Baggage Context Boundary & In-Flight PII Redaction Policy defines an industrial-grade behavioral standard for devops engineering. Enforces strict allowlists and automatic redaction boundaries on OpenTelemetry W3C Baggage propagation across distributed systems. Prohibits direct injection of raw Personally Identifiable Information (PII), unmasked account tokens, or internal multi-tenant credentials into cross-service headers. Requires cryptographic pseudonymization or gateway stripping before headers traverse 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: Propagating Raw PII and Multi-Tenant Isolation Secrets Across Services via Unrestricted 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 Raw PII and Multi-Tenant Isolation Secrets Across Services via Unrestricted 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 schema allowlist for keys propagated through OpenTelemetry Baggage (e.g., `request.id`, `routing.region`, `release.version`).

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.