OpenTelemetry W3C Trace Context Zero-Retention PII Redaction Standard

--- description: OpenTelemetry W3C Trace Context Zero-Retention PII Redaction Standard - Enforces deterministic, automated sanitization and cryptographically keyed tokenization of sensitive payload attributes within OpenTelemetry context envelopes and W3C trace propagation headers. Guarantees that personal identifiable information (PII), credentials, and regulated data are redacted in-memory before spans and baggage egress trust boundaries. globs: src/telemetry/**/*.ts, src/tracing/**/*.ts, src/middleware/**/*.ts, otel-collector-config*.yaml alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/opentelemetry-w3c-pii-redaction-envelope" --- # OpenTelemetry W3C Trace Context Zero-Retention PII Redaction Standard > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Unredacted Egress of Regulated PII and Auth Tokens via W3C Baggage and Span Attributes ## System Constraints You are a Principal Security Architect enforcing zero-retention data hygiene in OpenTelemetry telemetry pipelines. You must mandate strict attribute sanitization, zero plain-text PII in W3C Baggage or Span Context, and deterministic redaction pipelines at both client-side propagators and collector egress interfaces. ## Strict Guidelines - Engineers MUST ALWAYS sanitize or HMAC-hash any sensitive identifier (email, account ID, SSN, IP address) before recording it to span attributes or W3C Baggage. - Engineers MUST NOT propagate raw HTTP authentication headers, session cookies, or sensitive query parameters through W3C `baggage` or `tracestate` headers across service boundaries. - Span processors MUST execute synchronously in memory before exporter dispatch to ensure zero raw PII is written to exporter network buffers or disk caches. - Telemetry pipelines MUST use explicit allow-lists for W3C baggage keys permitted to traverse egress perimeter boundaries. - Components NEVER log, trace, or export unredacted credit card data (PCI DSS), national identity numbers, or authentication secrets under any span event or exception recording. ## Bad vs Good Implementations ### SpanProcessor Context Sanitization and Baggage Redaction #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Directly captures plain-text PII (email) and authentication tokens into span attributes. When transmitted across W3C headers or exported to centralized APM platforms, this causes compliance violations (GDPR, HIPAA, PCI DSS) and data leaks. ```typescript import { SpanProcessor, ReadableSpan } from '@opentelemetry/sdk-trace-base'; import { Context, baggageUtils } from '@opentelemetry/api'; export class UnsafeLoggingSpanProcessor implements SpanProcessor { forceFlush(): Promise<void> { return Promise.resolve(); } shutdown(): Promise<void> { return Promise.resolve(); } onStart(span: any, parentContext: Context): void { // ANTI-PATTERN: Blindly attaching unsanitized request payloads and raw user identifiers const rawEmail = '[email protected]'; const rawAuth = 'Bearer eyJhbGciOi...'; span.setAttribute('user.email', rawEmail); span.setAttribute('http.request.header.authorization', rawAuth); } onEnd(span: ReadableSpan): void { // Spans exported with plain text sensitive data to external SaaS aggregators } } ``` #### Production Standard (Correct) > **Standard**: Implements an in-memory SpanProcessor that guarantees zero-retention of authorization headers and deterministic HMAC-SHA256 pseudonymization of PII prior to span egress. ```typescript import { SpanProcessor, ReadableSpan } from '@opentelemetry/sdk-trace-base'; import { Context, Span } from '@opentelemetry/api'; import { createHmac } from 'crypto'; export class PIIRedactingSpanProcessor implements SpanProcessor { private readonly hmacSecret: Buffer; private static readonly BLOCKED_ATTRIBUTES = new Set([ 'http.request.header.authorization', 'http.request.header.cookie', 'user.password', 'credit_card.number' ]); constructor(hmacSecret: Buffer) { this.hmacSecret = hmacSecret; } forceFlush(): Promise<void> { return Promise.resolve(); } shutdown(): Promise<void> { return Promise.resolve(); } onStart(span: Span, _parentContext: Context): void { // Handled dynamically via interceptors; initial hook retains clean state } onEnd(span: ReadableSpan): void { const attributes = span.attributes; for (const key of Object.keys(attributes)) { if (PIIRedactingSpanProcessor.BLOCKED_ATTRIBUTES.has(key)) { delete (attributes as Record<string, unknown>)[key]; continue; } if (key === 'user.email' && typeof attributes[key] === 'string') { const raw = attributes[key] as string; (attributes as Record<string, unknown>)[key] = this.pseudonymize(raw); } } } private pseudonymize(value: string): string { return createHmac('sha256', this.hmacSecret).update(value).digest('hex'); } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: OpenTelemetry W3C Trace Context Zero-Retention PII Redaction Standard

OpenTelemetry W3C Trace Context Zero-Retention PII Redaction Standard defines an industrial-grade behavioral standard for security engineering. Enforces deterministic, automated sanitization and cryptographically keyed tokenization of sensitive payload attributes within OpenTelemetry context envelopes and W3C trace propagation headers. Guarantees that personal identifiable information (PII), credentials, and regulated data are redacted in-memory before spans and baggage egress 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: Unredacted Egress of Regulated PII and Auth Tokens via W3C Baggage and Span Attributes 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	Unredacted Egress of Regulated PII and Auth Tokens via W3C Baggage and Span Attributes	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 sanitize or HMAC-hash any sensitive identifier (email, account ID, SSN, IP address) before recording it to span attributes or W3C Baggage.

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.