OpenTelemetry Context Baggage Cardinality Budget and Sanitization Standard

Q: How does adopting this rule prevent AI hallucinations?

This rule explicitly declares what the AI must avoid (Unbounded Context Injection of Raw Customer Payloads and High-Cardinality Identifiers into W3C Baggage Headers) and prescribes verified positive examples. Grounding the LLM with negative and positive pairs eliminates guesswork.

Q: Which AI coding environments are supported?

This specification is multi-platform compatible: Cursor (.cursor/rules/*.mdc & .cursorrules), Anthropic Claude Code (CLAUDE.md), Windsurf (.windsurfrules), Codex / Cline (AGENTS.md), and GitHub Copilot (.github/copilot-instructions.md).

Q: Can I combine this rule with other technology stacks?

Yes. Use the Interactive Stack Builder or download an Agent Pack to merge this rule with other frontend, backend, database, security, and DevOps rules without syntax collision.

OpenTelemetry Context Baggage Cardinality Budget and Sanitization Standard

--- description: OpenTelemetry Context Baggage Cardinality Budget and Sanitization Standard - Enforces strict entry limits, byte-size budgets, and key/value sanitization on OpenTelemetry Baggage across distributed service boundaries. Uncontrolled context propagation leads to HTTP 431 Request Header Fields Too Large errors, downstream edge gateway drops, and downstream telemetry storage cost explosions. All distributed context mutations must undergo schema validation, length truncation, and allowlist filtering before propagation. globs: src/telemetry/**/*.{ts,js}, src/tracing/**/*.{ts,js}, src/middleware/**/*.{ts,js}, src/interceptors/**/*.{ts,js}, src/common/observability/**/*.{ts,js} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/otel-baggage-cardinality-budget-sanitization" --- # OpenTelemetry Context Baggage Cardinality Budget and Sanitization Standard > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: Unbounded Context Injection of Raw Customer Payloads and High-Cardinality Identifiers into W3C Baggage Headers ## System Constraints You are a Principal Engineer enforcing the OpenTelemetry Context Baggage Cardinality Budget and Sanitization Standard. Baggage carries operational metadata across process boundaries via the W3C Baggage header. You must strictly forbid the insertion of unvalidated user input, tokens, high-cardinality identifiers (such as UUIDs per transaction or arbitrary payloads), and unbounded strings into baggage context. Enforce an absolute budget: max 8 keys, max 64 bytes per key, max 128 bytes per value, total header footprint not exceeding 1024 bytes. Reject any code where baggage is used as a generic cache or payload forwarder. ## Strict Guidelines - Engineers MUST ALWAYS enforce strict size budgets on baggage: maximum 8 active key-value pairs, key length <= 64 bytes, value length <= 128 bytes, and aggregate baggage payload <= 1024 bytes. - Engineers MUST NOT inject PII (Personally Identifiable Information), auth tokens, raw request bodies, or ephemeral high-cardinality values (e.g., non-deterministic message hashes, full URLs) into OpenTelemetry Baggage. - Code MUST sanitize and allowlist baggage keys against an explicit runtime domain schema before appending them to the active context. - Services MUST silently drop or truncate incoming or outgoing baggage keys that exceed established size and cardinality limits rather than propagating invalid or bloated headers. - Components NEVER bridge raw HTTP query parameters or request headers directly into propagation context without explicit extraction, allowlisting, and sanitization. ## Bad vs Good Implementations ### Inbound Baggage Sanitization and Cardinality Enforcement Middleware #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Directly extracts and appends arbitrary request parameters and security credentials into Baggage. This violates W3C header size limits (causing 431 errors downriver), leaks sensitive auth tokens into downstream traces, and causes telemetry cardinality explosion. ```typescript import { Request, Response, NextFunction } from 'express'; import { propagation, context } from '@opentelemetry/api'; export function telemetryMiddleware(req: Request, _res: Response, next: NextFunction): void { // Anti-Pattern: Propagating raw headers and blindly injecting arbitrary // query parameters and unverified headers into the OpenTelemetry baggage context. let currentContext = propagation.extract(context.active(), req.headers); let baggage = propagation.getBaggage(currentContext) || propagation.createBaggage(); // Blindly injecting unvalidated query parameters (unbounded cardinality and size) for (const [key, val] of Object.entries(req.query)) { baggage = baggage.setEntry(key, { value: String(val) }); } // Injecting raw user agents or tenant tokens without bounds checking if (req.headers['authorization']) { baggage = baggage.setEntry('auth_token', { value: req.headers['authorization'] as string }); } context.with(propagation.setBaggage(currentContext, baggage), () => { next(); }); } ``` #### Production Standard (Correct) > **Standard**: Enforces strict allowlisting, item count budgeting (<= 8), per-key/value length truncations, and cumulative byte caps (1024 bytes) before setting the propagation context. Strips unauthorized parameters and prevents downstream HTTP 431 header overflow. ```typescript import { Request, Response, NextFunction } from 'express'; import { propagation, context, Baggage } from '@opentelemetry/api'; const MAX_BAGGAGE_ITEMS = 8; const MAX_KEY_LENGTH = 64; const MAX_VALUE_LENGTH = 128; const TOTAL_BUDGET_BYTES = 1024; // Explicit production allowlist for downstream baggage propagation const ALLOWED_BAGGAGE_KEYS = new Set<string>([ 'tenant.id', 'routing.environment', 'traffic.tier' ]); function sanitizeBaggage(rawBaggage: Baggage | undefined): Baggage { let cleanBaggage = propagation.createBaggage(); if (!rawBaggage) return cleanBaggage; let totalBytes = 0; let entryCount = 0; for (const [key, entry] of rawBaggage.getAllEntries()) { if (entryCount >= MAX_BAGGAGE_ITEMS) break; if (!ALLOWED_BAGGAGE_KEYS.has(key)) continue; if (key.length > MAX_KEY_LENGTH) continue; const sanitizedValue = entry.value.replace(/[^a-zA-Z0-9_.-]/g, '').slice(0, MAX_VALUE_LENGTH); const estimatedEntryBytes = key.length + sanitizedValue.length; if (totalBytes + estimatedEntryBytes > TOTAL_BUDGET_BYTES) break; cleanBaggage = cleanBaggage.setEntry(key, { value: sanitizedValue }); totalBytes += estimatedEntryBytes; entryCount++; } return cleanBaggage; } export function telemetryMiddleware(req: Request, _res: Response, next: NextFunction): void { const extractedContext = propagation.extract(context.active(), req.headers); const incomingBaggage = propagation.getBaggage(extractedContext); const boundedBaggage = sanitizeBaggage(incomingBaggage); const secureContext = propagation.setBaggage(extractedContext, boundedBaggage); context.with(secureContext, () => { next(); }); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: OpenTelemetry Context Baggage Cardinality Budget and Sanitization Standard

OpenTelemetry Context Baggage Cardinality Budget and Sanitization Standard defines an industrial-grade behavioral standard for devops engineering. Enforces strict entry limits, byte-size budgets, and key/value sanitization on OpenTelemetry Baggage across distributed service boundaries. Uncontrolled context propagation leads to HTTP 431 Request Header Fields Too Large errors, downstream edge gateway drops, and downstream telemetry storage cost explosions. All distributed context mutations must undergo schema validation, length truncation, and allowlist filtering before propagation. 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 Context Injection of Raw Customer Payloads and High-Cardinality Identifiers into W3C Baggage Headers 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 Context Injection of Raw Customer Payloads and High-Cardinality Identifiers into W3C Baggage Headers	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 enforce strict size budgets on baggage

Engineers MUST ALWAYS enforce strict size budgets on baggage: maximum 8 active key-value pairs, key length <= 64 bytes, value length <= 128 bytes, and aggregate baggage payload <= 1024 bytes.

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.