OpenTelemetry W3C Baggage Propagation & Zero-Leak In-Flight PII Redaction Pipeline

Q: How does adopting this rule prevent AI hallucinations?

This rule explicitly declares what the AI must avoid (Blind W3C Baggage Injection and Unsanitized Span Attribute Ingestion Causing PII Leakage and Metric Cardinality Explosion) and prescribes verified positive examples. Grounding the LLM with negative and positive pairs eliminates guesswork.

Q: Which AI coding environments are supported?

This specification is multi-platform compatible: Cursor (.cursor/rules/*.mdc & .cursorrules), Anthropic Claude Code (CLAUDE.md), Windsurf (.windsurfrules), Codex / Cline (AGENTS.md), and GitHub Copilot (.github/copilot-instructions.md).

Q: Can I combine this rule with other technology stacks?

Yes. Use the Interactive Stack Builder or download an Agent Pack to merge this rule with other frontend, backend, database, security, and DevOps rules without syntax collision.

OpenTelemetry W3C Baggage Propagation & Zero-Leak In-Flight PII Redaction Pipeline

--- description: OpenTelemetry W3C Baggage Propagation & Zero-Leak In-Flight PII Redaction Pipeline - Standardizes zero-overhead distributed trace correlation across heterogeneous runtimes while guaranteeing deterministic sanitization of high-cardinality telemetry data. Enforces strict boundary validation on W3C Baggage headers and mandates streaming span/log processor redaction to prevent accidental exfiltration of PII and credentials into downstream APM and observability backends. globs: src/telemetry/**/*.{ts,js}, src/observability/**/*.{ts,js}, src/instrumentation/**/*.{ts,js}, src/middleware/**/*.{ts,js}, src/server/**/*.{ts,js} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/opentelemetry-baggage-propagation-pii-redaction-pipeline" --- # OpenTelemetry W3C Baggage Propagation & Zero-Leak In-Flight PII Redaction Pipeline > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: Blind W3C Baggage Injection and Unsanitized Span Attribute Ingestion Causing PII Leakage and Metric Cardinality Explosion ## System Constraints You are a Principal Observability & Security Architect enforcing OpenTelemetry W3C Baggage context propagation invariants and zero-overhead in-flight PII redaction. You must strictly mandate that all Baggage attributes comply with strict schema allowlists and byte limits, span attributes are redacted via custom in-flight SpanProcessors before reaching any exporter, and high-cardinality PII (e.g., authorization headers, session tokens, emails, SSNs, raw IP addresses) is deterministically sanitized across all async boundaries. ## Strict Guidelines - Engineers MUST ALWAYS implement an in-flight `SpanProcessor` or `BatchSpanProcessor` wrapper that intercepts spans on `onEnd` or `onStart` to redact sensitive keys and values before exporting. - Engineers MUST NOT propagate raw HTTP headers, query parameters, or arbitrary user payload objects directly into W3C Baggage context or OpenTelemetry Span attributes. - Services MUST enforce an explicit allowlist and byte-size ceiling (e.g., maximum 8192 bytes total, max 64 key-value pairs) on incoming and outgoing W3C `baggage` headers to prevent header-bloat amplification attacks. - Telemetry pipelines MUST perform in-flight redaction using deterministic regex compilation or hashing masks (`[REDACTED_PII]`, SHA-256 for trace-joining identity without raw text) rather than client-side ad-hoc string replaces. - Components NEVER attach high-cardinality dynamic fields (like raw UUIDs, user IDs, or email addresses) directly to Metric dimensions or unindexed trace tags; use low-cardinality enum categories instead. - Engineers MUST ALWAYS configure the Composite TextMapPropagator with both `W3CTraceContextPropagator` and `W3CBaggagePropagator` explicitly registered at SDK initialization. ## Bad vs Good Implementations ### In-Flight PII Redaction SpanProcessor & Sanitized Baggage Propagation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Directly injecting raw authorization headers and emails into W3C Baggage propagates unencrypted sensitive data downstream to third parties and peer services. Dumping raw request bodies and card numbers into span attributes without an intermediate redacting SpanProcessor permanently leaks PCI/PII into APM backends and log aggregators. ```typescript import { trace, propagation, context } from '@opentelemetry/api'; import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node'; import { SimpleSpanProcessor, ConsoleSpanExporter } from '@opentelemetry/sdk-trace-base'; const provider = new NodeTracerProvider(); // ANTI-PATTERN: Direct exporter without redaction layer provider.addSpanProcessor(new SimpleSpanProcessor(new ConsoleSpanExporter())); provider.register(); export function handleRequest(req: any) { // ANTI-PATTERN: Injecting unvalidated raw headers and PII directly into Baggage and Spans const baggage = propagation.createBaggage({ 'user.email': { value: req.headers['x-user-email'] }, // PII in cross-service baggage 'auth.token': { value: req.headers['authorization'] } // Credential leakage }); const activeCtx = propagation.setBaggage(context.active(), baggage); const tracer = trace.getTracer('checkout-service'); return tracer.startActiveSpan('process_payment', {}, activeCtx, (span) => { span.setAttribute('customer.credit_card', req.body.cardNumber); // Direct PCI/PII leak span.setAttribute('http.request.headers', JSON.stringify(req.headers)); // Header dump span.end(); }); } ``` #### Production Standard (Correct) > **Standard**: Implements an explicit RedactingSpanProcessor that sanitizes attributes before dispatching to the BatchSpanProcessor. Strictly filters W3C Baggage inputs against an allowlist with byte-limit constraints to eliminate cardinality inflation, header buffer overflow, and downstream credential leakage. ```typescript import { trace, propagation, context, Span, Baggage, BaggageEntry } from '@opentelemetry/api'; import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node'; import { BatchSpanProcessor, SpanProcessor, ReadableSpan } from '@opentelemetry/sdk-trace-base'; import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-grpc'; import { W3CBaggagePropagator, W3CTraceContextPropagator, CompositePropagator } from '@opentelemetry/core'; // 1. In-flight PII Masking SpanProcessor const SENSITIVE_KEY_REGEX = /^(authorization|password|credit_card|token|email|ssn)$/i; const EMAIL_PATTERN = /[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/g; class RedactingSpanProcessor implements SpanProcessor { constructor(private readonly downstream: SpanProcessor) {} onStart(span: Span): void { this.downstream.onStart(span); } onEnd(span: ReadableSpan): void { const redactedAttributes = { ...span.attributes }; for (const [key, value] of Object.entries(redactedAttributes)) { if (SENSITIVE_KEY_REGEX.test(key)) { redactedAttributes[key] = '[REDACTED]'; } else if (typeof value === 'string') { redactedAttributes[key] = value.replace(EMAIL_PATTERN, '[REDACTED_EMAIL]'); } } // Mutate span attributes prior to export flush Object.assign(span.attributes, redactedAttributes); this.downstream.onEnd(span); } shutdown(): Promise<void> { return this.downstream.shutdown(); } forceFlush(): Promise<void> { return this.downstream.forceFlush(); } } // 2. Strict Baggage Allowlist Definition const BAGGAGE_ALLOWLIST = new Set(['tenant.id', 'service.tier', 'feature.flags']); const MAX_BAGGAGE_BYTES = 4096; export function sanitizeAndSetBaggage(entries: Record<string, string>): Baggage { const safeEntries: Record<string, BaggageEntry> = {}; let totalBytes = 0; for (const [k, v] of Object.entries(entries)) { if (BAGGAGE_ALLOWLIST.has(k)) { const entrySize = Buffer.byteLength(k, 'utf8') + Buffer.byteLength(v, 'utf8'); if (totalBytes + entrySize <= MAX_BAGGAGE_BYTES) { safeEntries[k] = { value: v }; totalBytes += entrySize; } } } return propagation.createBaggage(safeEntries); } // 3. Provider Initialization with Composite Propagation propagation.setGlobalPropagator(new CompositePropagator({ propagators: [new W3CTraceContextPropagator(), new W3CBaggagePropagator()], })); const exporter = new OTLPTraceExporter({ url: process.env.OTEL_EXPORTER_OTLP_ENDPOINT }); const provider = new NodeTracerProvider(); provider.addSpanProcessor(new RedactingSpanProcessor(new BatchSpanProcessor(exporter))); provider.register(); ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: OpenTelemetry W3C Baggage Propagation & Zero-Leak In-Flight PII Redaction Pipeline

OpenTelemetry W3C Baggage Propagation & Zero-Leak In-Flight PII Redaction Pipeline defines an industrial-grade behavioral standard for devops engineering. Standardizes zero-overhead distributed trace correlation across heterogeneous runtimes while guaranteeing deterministic sanitization of high-cardinality telemetry data. Enforces strict boundary validation on W3C Baggage headers and mandates streaming span/log processor redaction to prevent accidental exfiltration of PII and credentials into downstream APM and observability backends. 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: Blind W3C Baggage Injection and Unsanitized Span Attribute Ingestion Causing PII Leakage and Metric Cardinality Explosion 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	Blind W3C Baggage Injection and Unsanitized Span Attribute Ingestion Causing PII Leakage and Metric Cardinality Explosion	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 implement an in-flight `SpanProcessor` or `BatchSpanProcessor` wrapper that intercepts spans on `onEnd` or `onStart` to redact sensitive keys and values before exporting.

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.