Mandatory W3C Trace Context and Baggage Propagation Across Asynchronous Boundaries

--- description: Mandatory W3C Trace Context and Baggage Propagation Across Asynchronous Boundaries - Enforces strict extraction and injection of W3C Trace Context (traceparent, tracestate) and OpenTelemetry Baggage across asynchronous event brokers, background queues, and ephemeral micro-runtimes. Guarantees unbroken causal distributed telemetry and eliminates silent contextual leaks that break multi-tenant boundary isolation and request attribution. globs: src/**/*.{ts,js,mjs,cjs} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/opentelemetry-w3c-trace-context-baggage-propagation" --- # Mandatory W3C Trace Context and Baggage Propagation Across Asynchronous Boundaries > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: Firing Disconnected Async Tasks or Queue Messages Without Explicit W3C Context Carrier Injection ## System Constraints You are a Principal Observability Architect enforcing strict OpenTelemetry W3C Distributed Context and Baggage Propagation. Any message dispatched to an external bus, queue (e.g., Kafka, SQS, RabbitMQ), or asynchronous worker runtime MUST explicitly inject current active Context and Baggage into headers. Any consumer or receiver MUST explicitly extract the incoming Context and execute handlers within that activated Context via trace.setSpanContext or context.with. Context drops, unlinked detached promises, and unpropagated tenant isolation metadata are unacceptable. ## Strict Guidelines - Engineers MUST ALWAYS use OpenTelemetry's propagation.inject() with an explicit carrier interface before dispatching messages to Kafka, SQS, RabbitMQ, or any asynchronous message broker. - Engineers MUST ALWAYS extract parent contexts at asynchronous boundaries using propagation.extract() and wrap processing logic inside context.with() to maintain causal distributed lineage. - Engineers MUST NOT instantiate new root spans inside message consumers without explicitly linking the extracted incoming context via Link or creating the new span child of the extracted context. - Services MUST serialize and propagate multi-tenant isolation attributes (e.g., tenantId, organizationId) via OpenTelemetry Baggage alongside traceparent headers. - Components NEVER drop propagation headers when transforming, batching, or forwarding messages between internal worker micro-runtimes. ## Bad vs Good Implementations ### Async Message Publishing and Consumption Context Propagation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The producer publishes messages without injecting tracing headers (traceparent, baggage), completely severing the distributed trace. The consumer then starts an orphaned root span, destroying end-to-end latency visibility and losing tenant isolation context. ```typescript import { trace } from '@opentelemetry/api'; import { Producer, Consumer, EachMessagePayload } from 'kafkajs'; const tracer = trace.getTracer('payment-service'); export async function publishPaymentEvent(producer: Producer, payload: Record<string, unknown>): Promise<void> { // Anti-pattern: Dispatching message without injecting W3C traceparent or baggage headers await producer.send({ topic: 'payments', messages: [{ value: JSON.stringify(payload) }], }); } export async function registerPaymentConsumer(consumer: Consumer): Promise<void> { await consumer.run({ eachMessage: async ({ message }: EachMessagePayload) => { // Anti-pattern: New root trace created, dropping upstream causal context and tenant baggage const span = tracer.startSpan('process_payment'); try { console.log('Processing payment:', message.value?.toString()); } finally { span.end(); } }, }); } ``` #### Production Standard (Correct) > **Standard**: Uses propagation.inject to serialize W3C traceparent and baggage into Kafka headers, and propagation.extract combined with context.with on the receiving consumer. This guarantees unbroken causality and continuous propagation of isolation metadata across asynchronous boundaries. ```typescript import { context, propagation, trace, SpanKind, defaultTextMapGetter, defaultTextMapSetter } from '@opentelemetry/api'; import { Producer, Consumer, EachMessagePayload, IHeaders } from 'kafkajs'; const tracer = trace.getTracer('payment-service'); export async function publishPaymentEvent(producer: Producer, payload: Record<string, unknown>): Promise<void> { const headers: Record<string, string> = {}; // Invariant: Inject active context and baggage into the message header carrier propagation.inject(context.active(), headers, defaultTextMapSetter); const kafkaHeaders: IHeaders = Object.entries(headers).reduce((acc, [k, v]) => { acc[k] = Buffer.from(v); return acc; }, {} as IHeaders); await producer.send({ topic: 'payments', messages: [{ value: JSON.stringify(payload), headers: kafkaHeaders }], }); } export async function registerPaymentConsumer(consumer: Consumer): Promise<void> { await consumer.run({ eachMessage: async ({ message }: EachMessagePayload) => { const rawHeaders: Record<string, string> = {}; if (message.headers) { for (const [key, value] of Object.entries(message.headers)) { if (value) { rawHeaders[key] = Buffer.isBuffer(value) ? value.toString('utf8') : String(value); } } } // Invariant: Extract context from carrier and run execution block inside extracted context const parentContext = propagation.extract(context.active(), rawHeaders, defaultTextMapGetter); await context.with(parentContext, async () => { const span = tracer.startSpan('process_payment', { kind: SpanKind.CONSUMER }); try { console.log('Processing payment:', message.value?.toString()); } finally { span.end(); } }); }, }); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Mandatory W3C Trace Context and Baggage Propagation Across Asynchronous Boundaries

Mandatory W3C Trace Context and Baggage Propagation Across Asynchronous Boundaries defines an industrial-grade behavioral standard for devops engineering. Enforces strict extraction and injection of W3C Trace Context (traceparent, tracestate) and OpenTelemetry Baggage across asynchronous event brokers, background queues, and ephemeral micro-runtimes. Guarantees unbroken causal distributed telemetry and eliminates silent contextual leaks that break multi-tenant boundary isolation and request attribution. 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: Firing Disconnected Async Tasks or Queue Messages Without Explicit W3C Context Carrier Injection 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	Firing Disconnected Async Tasks or Queue Messages Without Explicit W3C Context Carrier Injection	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 use OpenTelemetry's propagation.inject() with an explicit carrier interface before dispatching messages to Kafka, SQS, RabbitMQ, or any asynchronous message broker.

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.