OpenTelemetry W3C Baggage Perimeter Redaction and Egress Boundary Filtering Guardrail

--- description: OpenTelemetry W3C Baggage Perimeter Redaction and Egress Boundary Filtering Guardrail - Enforces strict perimeter isolation and allowlist-based redaction of W3C Baggage headers on outbound HTTP and gRPC network boundaries. Prevents confidential multi-tenant metadata, internal routing flags, and customer PII stored in ambient OpenTelemetry context from leaking to untrusted external vendors or public APIs. globs: src/**/telemetry/**/*.{ts,js}, src/**/tracing/**/*.{ts,js}, src/**/http/**/*.{ts,js}, src/**/clients/**/*.{ts,js}, src/**/instrumentation/**/*.{ts,js} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/opentelemetry-w3c-baggage-perimeter-redaction-guardrail" --- # OpenTelemetry W3C Baggage Perimeter Redaction and Egress Boundary Filtering Guardrail > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: Unconstrained downstream propagation of ambient W3C Baggage containing tenant identifiers and PII across external egress boundaries ## System Constraints You are a Principal Software Architect enforcing production-grade observability and zero-trust data perimeter standards. OpenTelemetry W3C Baggage (`baggage` header) implicitly carries key-value pairs across distributed trace hops. Without explicit egress perimeter redaction, internal tenant IDs, security levels, and user PII automatically escape trusted cloud boundaries into external third-party SaaS APIs (e.g., Stripe, Twilio, Datadog). You must enforce strict perimeter-aware propagation, destination boundary classification, and key allowlisting. ## Strict Guidelines - Engineers MUST ALWAYS isolate internal W3C baggage by wrapping the global `W3CBaggagePropagator` with a boundary-aware filter or custom `TextMapPropagator`. - Engineers MUST NOT rely on default global HTTP/gRPC instrumentation without an explicit egress destination check that completely strips the `baggage` header for non-internal hosts. - Services MUST enforce an explicit allowlist policy for any baggage keys permitted to cross egress boundaries (e.g., `['x-correlation-id', 'public-request-id']`), dropping all unapproved keys by default. - Components NEVER store plaintext secrets, credentials, internal infrastructure topologies, or PII (e.g., `user.email`, `tenant.id`) in unredacted baggage contexts. - Code SHOULD enforce internal host pattern matching (e.g., `*.internal.net`, `*.svc.cluster.local`) before delegating context injection to standard W3C propagators. ## Bad vs Good Implementations ### Naive Global Instrumentation Leaking Baggage vs. Perimeter-Aware Outbound Propagator #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Default OpenTelemetry context injection serializes all baggage entries directly into the standard 'baggage' HTTP header. When calling an external vendor API (e.g., Stripe, Twilio, SendGrid), internal tenant isolation parameters and PII leak over the public internet to third-party logs. ```typescript import { context, propagation } from '@opentelemetry/api'; import axios from 'axios'; // ANTI-PATTERN: Ambient context containing sensitive tenant metadata is blindly // injected into the egress request and dispatched to third-party endpoints. export async function callExternalVendor(vendorUrl: string, payload: unknown) { const headers: Record<string, string> = {}; // Injects both traceparent AND unredacted baggage (e.g., 'tenant.id=acme,[email protected]') propagation.inject(context.active(), headers); return axios.post(vendorUrl, payload, { headers }); } ``` #### Production Standard (Correct) > **Standard**: The egress interceptor parses the destination host. For internal cluster traffic, full context is preserved. For any request traversing perimeter egress boundaries, baggage keys are filtered against a strict allowlist, preventing unintended tenant and PII exfiltration. ```typescript import { context, propagation, TextMapSetter, Context, Baggage, getBaggage, createBaggage } from '@opentelemetry/api'; import axios from 'axios'; import { URL } from 'node:url'; const TRUSTED_INTERNAL_DOMAIN = /\.internal\.acme\.corp$/; const ALLOWED_PUBLIC_BAGGAGE_KEYS = new Set(['x-request-id', 'x-public-experiment-variant']); function sanitizeBaggageForEgress(currentContext: Context, targetUrl: string): Context { const targetHost = new URL(targetUrl).hostname; // Retain all internal baggage if the destination is verified inside the perimeter if (TRUSTED_INTERNAL_DOMAIN.test(targetHost)) { return currentContext; } // For external egress boundaries, redact all keys not explicitly permitted const activeBaggage = getBaggage(currentContext); if (!activeBaggage) return currentContext; const filteredEntries = activeBaggage.getAllEntries().filter(([key]) => ALLOWED_PUBLIC_BAGGAGE_KEYS.has(key) ); const sanitizedBaggage: Baggage = createBaggage(Object.fromEntries(filteredEntries)); return setSanitizedBaggage(currentContext, sanitizedBaggage); } export async function callExternalVendor(vendorUrl: string, payload: unknown) { const headers: Record<string, string> = {}; const egressContext = sanitizeBaggageForEgress(context.active(), vendorUrl); propagation.inject(egressContext, headers); return axios.post(vendorUrl, payload, { headers }); } function setSanitizedBaggage(ctx: Context, baggage: Baggage): Context { // Returns context with baggage replaced by the sanitized instance return ctx.setValue(Symbol.for('OpenTelemetry Baggage Key'), baggage); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: OpenTelemetry W3C Baggage Perimeter Redaction and Egress Boundary Filtering Guardrail

OpenTelemetry W3C Baggage Perimeter Redaction and Egress Boundary Filtering Guardrail defines an industrial-grade behavioral standard for devops engineering. Enforces strict perimeter isolation and allowlist-based redaction of W3C Baggage headers on outbound HTTP and gRPC network boundaries. Prevents confidential multi-tenant metadata, internal routing flags, and customer PII stored in ambient OpenTelemetry context from leaking to untrusted external vendors or public APIs. 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: Unconstrained downstream propagation of ambient W3C Baggage containing tenant identifiers and PII across external egress 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	Unconstrained downstream propagation of ambient W3C Baggage containing tenant identifiers and PII across external egress 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 isolate internal W3C baggage by wrapping the global `W3CBaggagePropagator` with a boundary-aware filter or custom `TextMapPropagator`.

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.