OpenTelemetry Baggage-Driven Multi-Tenant Resource Attribution Standard

--- description: OpenTelemetry Baggage-Driven Multi-Tenant Resource Attribution Standard - Mandates tamper-resistant injection, verification, and extraction of OpenTelemetry W3C Baggage and TraceContext headers across asynchronous message brokers (e.g., Kafka, RabbitMQ, SQS). Ensures tenant identification, tiering, and cost-center metadata survive asynchronous boundaries for deterministic downstream cost allocation and fair-share rate limiting. Prevents unmetered orphan worker execution and downstream billing leakage. globs: src/producers/**/*.{ts,js,py,go}, src/consumers/**/*.{ts,js,py,go}, src/messaging/**/*.{ts,js,py,go}, src/telemetry/**/*.{ts,js,py,go} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/otel-baggage-tenant-attribution-standard" --- # OpenTelemetry Baggage-Driven Multi-Tenant Resource Attribution Standard > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: Unpropagated Broker Messages Causing Tenant Telemetry Severance and Downstream Cost Leaks ## System Constraints You are a Principal Software Architect enforcing the OpenTelemetry Baggage-Driven Multi-Tenant Resource Attribution Standard. You must mandate strict propagation, cryptographic verification, and extraction of tenant metadata across all message brokers to prevent unmetered infrastructure utilization and corrupted cost attribution. ## Strict Guidelines - Engineers MUST ALWAYS inject active OpenTelemetry W3C Baggage and TraceContext into message metadata headers via propagation.inject prior to broker dispatch. - Engineers MUST ALWAYS extract carrier headers via propagation.extract at consumer entrypoints and wrap execution inside the extracted context using context.with. - Engineers MUST validate tenant identity against an HMAC signature or trusted schema registry when accepting baggage from external or semi-trusted message producers. - Services MUST record downstream compute metrics (CPU time, memory footprint, external I/O tokens) with tenant dimensions extracted directly from verified Baggage. - Workers MUST NEVER execute un-attributed background operations; messages lacking valid tenant Baggage MUST be routed to a dead-letter quarantine queue. ## Bad vs Good Implementations ### Asynchronous Message Context Propagation with OpenTelemetry Baggage #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Publishing messages with tenant metadata embedded purely in the payload drops trace context and OpenTelemetry baggage headers. Downstream consumers execute in disconnected root contexts, leaving compute, DB calls, and 3rd-party API expenses unattributed to the tenant. ```typescript import { Producer } from 'kafkajs'; // ANTI-PATTERN: Emits message without W3C trace/baggage propagation export async function publishOrderEvent(producer: Producer, orderId: string, tenantId: string) { await producer.send({ topic: 'orders.processing', messages: [ { key: orderId, value: JSON.stringify({ orderId, tenantId, amount: 99.99 }), // Missing OpenTelemetry baggage propagation: worker cannot attribute compute costs }, ], }); } ``` #### Production Standard (Correct) > **Standard**: Injects W3C Baggage containing tenant identifiers and an HMAC integrity signature into the Kafka message headers. Downstream consumers can extract the exact context, verify data authenticity, and accurately attribute downstream resource costs. ```typescript import { Producer, Message } from 'kafkajs'; import { context, propagation, trace, Baggage, createBaggage } from '@opentelemetry/api'; import { createHmac } from 'crypto'; const BAGGAGE_SIGNING_SECRET = process.env.TELEMETRY_SIGNING_KEY || 'production-secret'; export async function publishOrderEvent(producer: Producer, orderId: string, tenantId: string, tier: string) { const tracer = trace.getTracer('orders-service'); return tracer.startActiveSpan('publishOrderEvent', async (span) => { try { const signature = createHmac('sha256', BAGGAGE_SIGNING_SECRET) .update(`${tenantId}:${tier}`) .digest('hex'); const tenantBaggage: Baggage = createBaggage({ 'tenant.id': { value: tenantId }, 'tenant.tier': { value: tier }, 'tenant.sig': { value: signature }, }); const activeContext = propagation.setBaggage(context.active(), tenantBaggage); const carrier: Record<string, string> = {}; propagation.inject(activeContext, carrier); const message: Message = { key: orderId, value: JSON.stringify({ orderId, amount: 99.99 }), headers: Object.entries(carrier).reduce((acc, [k, v]) => { acc[k] = Buffer.from(v); return acc; }, {} as Record<string, Buffer>), }; await producer.send({ topic: 'orders.processing', messages: [message], }); } finally { span.end(); } }); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: OpenTelemetry Baggage-Driven Multi-Tenant Resource Attribution Standard

OpenTelemetry Baggage-Driven Multi-Tenant Resource Attribution Standard defines an industrial-grade behavioral standard for devops engineering. Mandates tamper-resistant injection, verification, and extraction of OpenTelemetry W3C Baggage and TraceContext headers across asynchronous message brokers (e.g., Kafka, RabbitMQ, SQS). Ensures tenant identification, tiering, and cost-center metadata survive asynchronous boundaries for deterministic downstream cost allocation and fair-share rate limiting. Prevents unmetered orphan worker execution and downstream billing leakage. 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: Unpropagated Broker Messages Causing Tenant Telemetry Severance and Downstream Cost Leaks 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	Unpropagated Broker Messages Causing Tenant Telemetry Severance and Downstream Cost Leaks	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 inject active OpenTelemetry W3C Baggage and TraceContext into message metadata headers via propagation.inject prior to broker dispatch.

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.