OpenTelemetry Baggage Size Quota & Context Propagation Guardrail

--- description: OpenTelemetry Baggage Size Quota & Context Propagation Guardrail - Enforces deterministic boundaries on W3C OpenTelemetry baggage context propagation to prevent HTTP 431 Request Header Fields Too Large cascades and memory exhaustion. Mandates strict key whitelisting, per-entry value size caps, and total payload limits across downstream distributed RPC hops. globs: src/tracing/**/*.{ts,js}, src/middleware/**/*.{ts,js}, src/infrastructure/telemetry/**/*.{ts,js}, src/common/context/**/*.{ts,js} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/opentelemetry-baggage-size-quota-guardrail" --- # OpenTelemetry Baggage Size Quota & Context Propagation Guardrail > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: Unbounded distributed context propagation causing downstream 431 DOS and header inflation ## System Constraints You are a Principal Software Architect enforcing enterprise distributed tracing boundaries. Baggage in OpenTelemetry is propagated downstream across process boundaries via HTTP and gRPC headers. Unrestricted injection of high-cardinality data, security tokens, or large payloads into baggage bloats header footprints, triggering upstream reverse-proxy drops, edge Envoy/Nginx 431 errors, and memory pressure. You must enforce strict key allowlists, strict character byte length caps, and aggressive entry count limits at every propagation boundary. ## Strict Guidelines - Engineers MUST ALWAYS validate baggage keys against an immutable strict allowlist (e.g., `tenant_id`, `request_tier`, `origin_region`) before mutation. - Engineers MUST NOT propagate identity tokens, JSON payloads, user profile blobs, or high-cardinality telemetry metrics via OpenTelemetry baggage. - Services MUST enforce a hard maximum total baggage payload size limit of 1024 bytes and a maximum of 8 key-value entries across all propagated contexts. - Code SHOULD sanitize individual baggage values to a maximum length of 128 bytes and truncate or reject payloads that violate RFC 7230 header token specifications. - Components NEVER propagate unvalidated incoming request headers directly into downstream baggage without sanitization and length validation. ## Bad vs Good Implementations ### Unbounded Baggage Injection vs. Strict Allowlist and Size-Capped Baggage Propagator #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Arbitrary header propagation and stringified JSON objects blow past safe HTTP header limits (typically 4KB–8KB total on proxies like Envoy/NGINX). When forwarded across multi-tier microservices, header sizes accumulate, leading to cascading HTTP 431 (Request Header Fields Too Large) outages. ```typescript import { propagation, context } from '@opentelemetry/api'; import { Request, Response, NextFunction } from 'express'; export function tracingMiddleware(req: Request, res: Response, next: NextFunction): void { // ANTI-PATTERN: Dynamically copying arbitrary request headers and large user metadata into baggage. // Causes downstream HTTP 431 failures in deep call graphs. let activeBaggage = propagation.getBaggage(context.active()) || propagation.createBaggage(); const rawMetadata = req.headers['x-custom-metadata']; if (typeof rawMetadata === 'string') { activeBaggage = activeBaggage.setEntry('metadata', { value: rawMetadata }); } // Propagating full user context directly if (req.user) { activeBaggage = activeBaggage.setEntry('user_payload', { value: JSON.stringify(req.user) }); } context.with(propagation.setBaggage(context.active(), activeBaggage), () => { next(); }); } ``` #### Production Standard (Correct) > **Standard**: Implements defensive limits: filters by strict key allowlist, bounds individual value length to 128 bytes, enforces an absolute 1024-byte ceiling, and limits maximum entries to 8, guaranteeing immunity from downstream header bloat. ```typescript import { propagation, context, Baggage, BaggageEntry } from '@opentelemetry/api'; import { Request, Response, NextFunction } from 'express'; const ALLOWED_BAGGAGE_KEYS = new Set(['tenant_id', 'tier', 'origin_dc', 'correlation_id']); const MAX_BAGGAGE_BYTES = 1024; const MAX_ENTRY_VALUE_BYTES = 128; const MAX_ALLOWED_ENTRIES = 8; function calculateBaggageSize(baggage: Baggage): number { return baggage.getAllEntries().reduce((total, [key, entry]) => { return total + Buffer.byteLength(key, 'utf8') + Buffer.byteLength(entry.value, 'utf8'); }, 0); } export function secureBaggageMiddleware(req: Request, res: Response, next: NextFunction): void { const currentContext = context.active(); let currentBaggage = propagation.getBaggage(currentContext) || propagation.createBaggage(); // Filter out any inherited baggage entries not explicitly allowlisted const validatedEntries: Record<string, BaggageEntry> = {}; let currentSize = 0; let entryCount = 0; for (const [key, entry] of currentBaggage.getAllEntries()) { if (ALLOWED_BAGGAGE_KEYS.has(key) && entryCount < MAX_ALLOWED_ENTRIES) { const sanitizedValue = entry.value.slice(0, MAX_ENTRY_VALUE_BYTES); const entryBytes = Buffer.byteLength(key, 'utf8') + Buffer.byteLength(sanitizedValue, 'utf8'); if (currentSize + entryBytes <= MAX_BAGGAGE_BYTES) { validatedEntries[key] = { value: sanitizedValue }; currentSize += entryBytes; entryCount++; } } } // Safely inject validated caller attributes const tenantId = req.headers['x-tenant-id']; if (typeof tenantId === 'string' && ALLOWED_BAGGAGE_KEYS.has('tenant_id') && entryCount < MAX_ALLOWED_ENTRIES) { const sanitizedTenant = tenantId.slice(0, MAX_ENTRY_VALUE_BYTES); const candidateBytes = Buffer.byteLength('tenant_id', 'utf8') + Buffer.byteLength(sanitizedTenant, 'utf8'); if (currentSize + candidateBytes <= MAX_BAGGAGE_BYTES) { validatedEntries['tenant_id'] = { value: sanitizedTenant }; } } const boundedBaggage = propagation.createBaggage(validatedEntries); context.with(propagation.setBaggage(currentContext, boundedBaggage), () => { next(); }); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: OpenTelemetry Baggage Size Quota & Context Propagation Guardrail

OpenTelemetry Baggage Size Quota & Context Propagation Guardrail defines an industrial-grade behavioral standard for devops engineering. Enforces deterministic boundaries on W3C OpenTelemetry baggage context propagation to prevent HTTP 431 Request Header Fields Too Large cascades and memory exhaustion. Mandates strict key whitelisting, per-entry value size caps, and total payload limits across downstream distributed RPC hops. 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: Unbounded distributed context propagation causing downstream 431 DOS and header inflation 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	Unbounded distributed context propagation causing downstream 431 DOS and header inflation	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 validate baggage keys against an immutable strict allowlist (e.g., `tenant_id`, `request_tier`, `origin_region`) before mutation.

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.