OpenTelemetry GenAI Semantic Protocol Baggage and Distributed Causality Invariant

--- description: OpenTelemetry GenAI Semantic Protocol Baggage and Distributed Causality Invariant - Enforces strict distributed context propagation and W3C Baggage preservation across asynchronous streaming LLM pipelines and multi-agent DAGs. Mandates deterministic recording of OpenTelemetry GenAI semantic conventions, Time-to-First-Token (TTFT) metrics, and cost-attribution baggage across asynchronous yield boundaries without context detachment. globs: src/llm/**/*.{ts,tsx}, src/services/ai/**/*.{ts,tsx}, src/telemetry/**/*.{ts,tsx}, src/orchestrators/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/otel-genai-baggage-context-causality-invariant" --- # OpenTelemetry GenAI Semantic Protocol Baggage and Distributed Causality Invariant > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: Context bleed and detached trace causality during async generator stream iteration leading to unallocated token costs and missing TTFT metrics. ## System Constraints You are a Principal Software Architect enforcing the OpenTelemetry GenAI Semantic Protocol Baggage Invariant. You must guarantee that all LLM calls, streaming generators, and multi-agent orchestrations propagate W3C TraceContext and Baggage across asynchronous event boundaries. Ensure accurate tracking of time-to-first-token (TTFT), token consumption, and cost attribution metadata without context dropping. ## Strict Guidelines - Engineers MUST ALWAYS bind async iterables and streaming callbacks to the active OpenTelemetry context using `context.bind()` or execute inside `context.with()` scopes to avoid context detachment across yield boundaries. - Engineers MUST set W3C Baggage entries for tenant, session, and cost center attribution (`gen_ai.customer.id`, `gen_ai.cost_center`, `workflow.id`) prior to invoking LLM inference calls. - Services MUST emit a discrete span event or metric recording `gen_ai.client.time_to_first_token` immediately upon receiving the first stream chunk before yielding to downstream consumers. - Engineers MUST NOT instantiate raw LLM streaming requests without passing explicit parent `Context` or extracting propagation headers in background queues or agent worker pools. - Components NEVER drop token usage metrics (`gen_ai.usage.input_tokens`, `gen_ai.usage.output_tokens`) from final stream chunks or server response envelopes; metrics MUST be finalized on the parent span before `span.end()`. ## Bad vs Good Implementations ### Propagating OTel Context and Capturing TTFT across Streaming LLM Generators #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The active span context is not propagated through baggage, downstream workers cannot attribute costs to the customer, TTFT is completely unmeasured, and span context drops across the async generator iteration boundary. ```typescript import { trace } from '@opentelemetry/api'; import OpenAI from 'openai'; const tracer = trace.getTracer('llm-service'); const openai = new OpenAI(); export async function* streamCompletion(prompt: string, customerId: string) { const span = tracer.startSpan('chat.completions.stream'); // BUG: Baggage is ignored; tenant cost attribution is lost downstream // BUG: Context is not bound across async yield boundaries const stream = await openai.chat.completions.create({ model: 'gpt-4o', messages: [{ role: 'user', content: prompt }], stream: true, }); for await (const chunk of stream) { // BUG: Missing TTFT calculation and context-bound telemetry event yield chunk.choices[0]?.delta?.content || ''; } span.end(); } ``` #### Production Standard (Correct) > **Standard**: Baggage is properly initialized and propagated with `customerId` for downstream chargebacks. Time-to-First-Token (TTFT) is captured using high-resolution timers and emitted as a GenAI semantic event. Yielded chunks maintain active context binding via `context.bind` and `context.with`. ```typescript import { trace, context, propagation, HrTime } from '@opentelemetry/api'; import { hrTime, hrTimeDuration } from '@opentelemetry/core'; import OpenAI from 'openai'; const tracer = trace.getTracer('llm-service'); const openai = new OpenAI(); export async function* streamCompletion(prompt: string, customerId: string): AsyncGenerator<string, void, unknown> { // Invariant: Bind tenant & billing context via W3C Baggage let baggage = propagation.getBaggage(context.active()) || propagation.createBaggage(); baggage = baggage.setEntry('gen_ai.customer.id', { value: customerId }); const contextWithBaggage = propagation.setBaggage(context.active(), baggage); return yield* context.with(contextWithBaggage, async function* () { const span = tracer.startSpan('chat.completions.stream', { attributes: { 'gen_ai.system': 'openai', 'gen_ai.request.model': 'gpt-4o', 'gen_ai.customer.id': customerId, }, }); const boundContext = trace.setSpan(context.active(), span); const startTime: HrTime = hrTime(); let isFirstChunk = true; let totalOutputTokens = 0; try { const stream = await openai.chat.completions.create({ model: 'gpt-4o', messages: [{ role: 'user', content: prompt }], stream: true, stream_options: { include_usage: true }, }); for await (const chunk of stream) { if (isFirstChunk) { const duration = hrTimeDuration(startTime, hrTime()); const ttftMs = duration[0] * 1000 + duration[1] / 1e6; span.addEvent('gen_ai.client.time_to_first_token', { 'gen_ai.response.ttft_ms': ttftMs }); span.setAttribute('gen_ai.response.time_to_first_token_ms', ttftMs); isFirstChunk = false; } if (chunk.usage) { span.setAttribute('gen_ai.usage.input_tokens', chunk.usage.prompt_tokens); span.setAttribute('gen_ai.usage.output_tokens', chunk.usage.completion_tokens); } const delta = chunk.choices[0]?.delta?.content || ''; if (delta) { totalOutputTokens++; // Invariant: Retain active context across downstream iteration yield context.bind(boundContext, () => delta)(); } } } catch (error) { span.recordException(error as Error); span.setStatus({ code: 2, message: (error as Error).message }); throw error; } finally { span.end(); } })(); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: OpenTelemetry GenAI Semantic Protocol Baggage and Distributed Causality Invariant

OpenTelemetry GenAI Semantic Protocol Baggage and Distributed Causality Invariant defines an industrial-grade behavioral standard for devops engineering. Enforces strict distributed context propagation and W3C Baggage preservation across asynchronous streaming LLM pipelines and multi-agent DAGs. Mandates deterministic recording of OpenTelemetry GenAI semantic conventions, Time-to-First-Token (TTFT) metrics, and cost-attribution baggage across asynchronous yield boundaries without context detachment. 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: Context bleed and detached trace causality during async generator stream iteration leading to unallocated token costs and missing TTFT metrics. 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	Context bleed and detached trace causality during async generator stream iteration leading to unallocated token costs and missing TTFT metrics.	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 bind async iterables and streaming callbacks to the active OpenTelemetry context using `context.bind()` or execute inside `context.with()` scopes to avoid context detachment across yield boundaries.

Engineers MUST ALWAYS bind async iterables and streaming callbacks to the active OpenTelemetry context using `context.bind()` or execute inside `context.with()` scopes to avoid context detachment across yield boundaries.

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.