Strict W3C Distributed Context & Baggage Propagation Across Async Queues

--- description: Strict W3C Distributed Context & Baggage Propagation Across Async Queues - Enforces deterministic extraction and injection of OpenTelemetry W3C traceparent and baggage metadata across asynchronous queue boundaries (Kafka, SQS, RabbitMQ, BullMQ). Eliminates trace fragmentation and orphan spans by ensuring consumers restore caller context or establish explicit span links before executing worker logic. globs: src/**/*queue*/**/*.{ts,js}, src/**/*worker*/**/*.{ts,js}, src/**/*consumer*/**/*.{ts,js}, src/**/*producer*/**/*.{ts,js}, src/**/*event*/**/*.{ts,js}, src/**/*bus*/**/*.{ts,js} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/opentelemetry-w3c-queue-context-propagation" --- # Strict W3C Distributed Context & Baggage Propagation Across Async Queues > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: Silent Trace Fragmentation via In-Band Payload Dispatch without W3C Context Carrier Injection ## System Constraints You are a Principal Software Architect enforcing production-grade OpenTelemetry observability standards. Async task dispatches across message brokers MUST preserve distributed trace state and transactional baggage across process boundaries. You must reject any queue producer or consumer implementation that fails to inject or extract W3C Trace Context and Baggage via OpenTelemetry API propagation primitives. ## Strict Guidelines - Engineers MUST ALWAYS use 'propagation.inject(context.active(), carrier)' on message publishing boundaries to populate headers with W3C 'traceparent', 'tracestate', and 'baggage'. - Engineers MUST NOT rely on implicit process-local Context inside asynchronous queue jobs; worker handlers must execute 'propagation.extract(ROOT_CONTEXT, carrier)' before invoking application logic. - Services MUST serialize extracted span context into an active span parent via 'context.with(extractedContext, ...)' or record the extracted context via SpanLinks if processing batched messages. - Engineers MUST validate the existence and structural validity of 'traceparent' in message payloads or message transport attributes during envelope deserialization. - Components NEVER catch context propagation errors silently; serialization failures must trigger operational alerts and fallback trace linking. ## Bad vs Good Implementations ### Queue Producer and Consumer with W3C Context Carrier Propagation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The producer publishes the message without injecting active tracing context into message headers/attributes. The consumer initiates a new active span from the ambient process context rather than extracting context from the incoming envelope, resulting in an orphaned trace and broken end-to-end distributed observability. ```typescript import { Queue, Worker, Job } from 'bullmq'; import { trace } from '@opentelemetry/api'; const queue = new Queue('order-processing'); const tracer = trace.getTracer('order-service'); // Producer dispatches message without carrier injection export async function enqueueOrder(orderId: string, customerId: string) { await tracer.startActiveSpan('enqueueOrder', async (span) => { // ANTI-PATTERN: Only raw data sent, traceparent & baggage dropped await queue.add('process', { orderId, customerId }); span.end(); }); } // Consumer creates disconnected orphan root span new Worker('order-processing', async (job: Job) => { // ANTI-PATTERN: Trace fragmentation; starts brand new root trace await tracer.startActiveSpan('processOrder', async (span) => { await processOrderBusinessLogic(job.data.orderId); span.end(); }); }); ``` #### Production Standard (Correct) > **Standard**: Production invariant compliant implementation ensuring memory safety, deterministic execution, and zero runtime hallucination. ```typescript import { Queue, Worker, Job } from 'bullmq'; import { trace, context, propagation, ROOT_CONTEXT, SpanKind } from '@opentelemetry/api'; interface MessageEnvelope<T> { payload: T; traceCarrier: Record<string, string>; } interface OrderPayload { orderId: string; customerId: string; } const queue = new Queue<MessageEnvelope<OrderPayload>>('order-processing'); const tracer = trace.getTracer('order-service'); // Producer explicitly injects active context into envelope carrier export async function enqueueOrder(orderId: string, customerId: string): Promise<void> { await tracer.startActiveSpan('enqueueOrder', { kind: SpanKind.PRODUCER }, async (span) => { try { const traceCarrier: Record<string, string> = {}; propagation.inject(context.active(), traceCarrier); await queue.add('process', { payload: { orderId, customerId }, traceCarrier, }); } finally { span.end(); } }); } // Consumer extracts context from carrier and binds it to worker execution new Worker<MessageEnvelope<OrderPayload>>('order-processing', async (job: Job<MessageEnvelope<OrderPayload>>) => { const extractedContext = propagation.extract(ROOT_CONTEXT, job.data.traceCarrier ?? {}); await context.with(extractedContext, async () => { await tracer.startActiveSpan( `processOrder ${job.name}`, { kind: SpanKind.CONSUMER }, async (span) => { try { await processOrderBusinessLogic(job.data.payload.orderId); } catch (error) { span.recordException(error as Error); throw error; } finally { span.end(); } } ); }); }); ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Strict W3C Distributed Context & Baggage Propagation Across Async Queues

Strict W3C Distributed Context & Baggage Propagation Across Async Queues defines an industrial-grade behavioral standard for devops engineering. Enforces deterministic extraction and injection of OpenTelemetry W3C traceparent and baggage metadata across asynchronous queue boundaries (Kafka, SQS, RabbitMQ, BullMQ). Eliminates trace fragmentation and orphan spans by ensuring consumers restore caller context or establish explicit span links before executing worker logic. 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: Silent Trace Fragmentation via In-Band Payload Dispatch without 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	Silent Trace Fragmentation via In-Band Payload Dispatch without 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 'propagation.inject(context.active(), carrier)' on message publishing boundaries to populate headers with W3C 'traceparent', 'tracestate', and '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.