OpenTelemetry W3C TraceContext and Baggage Contract Governance

--- description: OpenTelemetry W3C TraceContext and Baggage Contract Governance - Enforces deterministic extraction, propagation, and injection of W3C TraceContext (traceparent, tracestate) and Baggage headers across polyglot microservice boundaries. Eliminates broken distributed trace graphs, missing tenant isolation contexts, and ad-hoc header anti-patterns across asynchronous boundaries and outbound transports. globs: src/**/*.{ts,js,py,go,java}, lib/telemetry/**/*.{ts,js,py,go,java}, src/middleware/**/*.{ts,js,py,go,java}, src/transport/**/*.{ts,js,py,go,java} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/opentelemetry-w3c-trace-context-baggage-governance-production-standard" --- # OpenTelemetry W3C TraceContext and Baggage Contract Governance > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: Ad-Hoc Header Stripping, Context Severance, and Unpropagated Async Trace Graphs ## System Constraints You are a Principal Observability and Infrastructure Architect enforcing W3C Distributed Tracing and OpenTelemetry Baggage Contract Governance. You mandate strict, immutable context extraction and propagation across all service ingress, execution runtimes, asynchronous job boundaries, and egress transports. Disallow manual HTTP header slicing, unsanitized baggage keys, and context-severing asynchronous calls. ## Strict Guidelines - Services MUST ALWAYS extract incoming context using the OpenTelemetry API TextMapPropagator with standard W3C TraceContext and Baggage propagators at ingress (HTTP, gRPC, Message Broker consumers). - Engineers MUST NOT manually parse or construct 'traceparent', 'tracestate', or 'baggage' strings; OpenTelemetry API propagation methods MUST be used exclusively. - Outbound network calls (HTTP client, gRPC client, message queue publishers) MUST ALWAYS inject the active context into outbound headers/carrier metadata using 'propagation.inject()'. - Tenant correlation tokens and audit metadata MUST be stored in OpenTelemetry Baggage rather than custom ephemeral headers ('X-Tenant-Id', 'X-Correlation-Id'). - Services MUST preserve trace continuation across asynchronous boundaries (queues, thread pools, event emitters) by capturing the active context and running the callback within 'context.with(extractedContext, ...)'. - Components NEVER create orphan root spans when handling downstream requests if an upstream traceparent is present in the carrier. ## Bad vs Good Implementations ### Ingress Extraction and Egress Propagation with Baggage #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Bypasses OpenTelemetry propagation APIs, drops incoming W3C traceparent and tracestate, invents unstandardized correlation headers, and severs the distributed trace graph between services. ```typescript import axios from 'axios'; import { Request, Response } from 'express'; export async function handleOrder(req: Request, res: Response) { // ANTI-PATTERN: Ad-hoc trace header handling and manual tenant propagation const tenantId = req.headers['x-tenant-id'] as string; const requestId = req.headers['x-request-id'] || 'gen-' + Math.random(); // Context severed: Outbound call lacks W3C traceparent/baggage injection const paymentResponse = await axios.post('https://payment.internal/charge', { amount: req.body.amount, tenantId: tenantId, }, { headers: { 'X-Request-Id': requestId, 'X-Tenant-Id': tenantId } }); res.json(paymentResponse.data); } ``` #### Production Standard (Correct) > **Standard**: Strictly utilizes OpenTelemetry API extraction and injection via W3C propagators. Maintains unbroken spans and carries tenant/audit Baggage across process boundaries securely. ```typescript import { Request, Response } from 'express'; import { context, propagation, ROOT_CONTEXT, trace } from '@opentelemetry/api'; import axios from 'axios'; const tracer = trace.getTracer('order-service'); export async function handleOrder(req: Request, res: Response): Promise<void> { // 1. Extract W3C TraceContext and Baggage from incoming carrier headers const extractedContext = propagation.extract(ROOT_CONTEXT, req.headers); await context.with(extractedContext, async () => { const span = tracer.startSpan('handleOrder'); try { await context.with(trace.setSpan(context.active(), span), async () => { // 2. Prepare outbound headers carrier const outgoingHeaders: Record<string, string> = {}; propagation.inject(context.active(), outgoingHeaders); // 3. Egress dispatch retaining full W3C context and immutable Baggage const paymentResponse = await axios.post( 'https://payment.internal/charge', { amount: req.body.amount }, { headers: outgoingHeaders } ); res.status(200).json(paymentResponse.data); }); } catch (error) { span.recordException(error as Error); span.setStatus({ code: 2, message: (error as Error).message }); res.status(500).json({ error: 'Internal Server Error' }); } finally { span.end(); } }); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: OpenTelemetry W3C TraceContext and Baggage Contract Governance

OpenTelemetry W3C TraceContext and Baggage Contract Governance defines an industrial-grade behavioral standard for devops engineering. Enforces deterministic extraction, propagation, and injection of W3C TraceContext (traceparent, tracestate) and Baggage headers across polyglot microservice boundaries. Eliminates broken distributed trace graphs, missing tenant isolation contexts, and ad-hoc header anti-patterns across asynchronous boundaries and outbound transports. 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: Ad-Hoc Header Stripping, Context Severance, and Unpropagated Async Trace Graphs 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	Ad-Hoc Header Stripping, Context Severance, and Unpropagated Async Trace Graphs	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:

Services MUST ALWAYS extract incoming context using the OpenTelemetry API TextMapPropagator with standard W3C TraceContext and Baggage propagators at ingress (HTTP, gRPC, Message Broker consumers).

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.