OpenTelemetry Distributed Baggage & Tail-Based Sampling Standard

Q: How does adopting this rule prevent AI hallucinations?

This rule explicitly declares what the AI must avoid (Overloading W3C Baggage with Unsanitized PII and Relying on Naive Head-Based Sampling for Error Paths) 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 Distributed Baggage & Tail-Based Sampling Standard

--- description: OpenTelemetry Distributed Baggage & Tail-Based Sampling Standard - Mandates strict separation between transient span attributes and distributed W3C baggage, enforcing baggage hygiene to prevent header bloat and PII leakage across RPC boundaries. Pairs contextual baggage propagation with tail-based OpenTelemetry Collector sampling configurations to guarantee 100% trace capture for critical errors and high-tier tenants while suppressing routine high-volume spans. globs: src/**/*.{ts,js,py,go}, **/otel-collector*.{yaml,yml}, **/telemetry*.{ts,js} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/opentelemetry-baggage-semantic-sampling-standard" --- # OpenTelemetry Distributed Baggage & Tail-Based Sampling Standard > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: Overloading W3C Baggage with Unsanitized PII and Relying on Naive Head-Based Sampling for Error Paths ## System Constraints You are a Principal Observability Architect enforcing OpenTelemetry standards. Prevent telemetry pipeline saturation and data leakage by strictly regulating W3C Baggage usage and mandating tail-based sampling strategies. Ensure baggage values are low-cardinality, non-PII, explicitly extracted into span attributes when queryable, and configured with tail-based sampling policies that guarantee 100% retention for status_code >= 500 and high-SLA accounts. ## Strict Guidelines - Engineers MUST ALWAYS sanitize W3C Baggage and restrict keys to low-cardinality operational metadata (e.g., `tenant.tier`, `account.id`), strictly prohibiting PII, large payloads, or secrets. - Engineers MUST NOT assume distributed baggage is automatically indexed as span attributes; services MUST explicitly read baggage values and attach them to local spans if required for query filtering or collector sampling. - Services MUST configure OpenTelemetry tail-based sampling pipelines in the collector to guarantee 100% capture of spans with `error=true`, `http.status_code >= 500`, or latency above the p99 threshold. - Code SHOULD enforce size limits (<1KB total baggage payload) to avoid HTTP header overflow errors (HTTP 431) during multi-hop context propagation. - Components NEVER drop traces at the head when deploying asynchronous distributed topologies handling billing, payments, or critical transaction pathways. ## Bad vs Good Implementations ### Proper Baggage Propagation and Local Span Attribute Attachment #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Injecting sensitive user profiles and tokens into baggage causes massive HTTP header inflation, leaks secrets down the RPC chain, and fails to expose operational attributes to local spans. A simple head-based probabilistic sampler will drop a high percentage of these traces, hiding production exceptions. ```typescript import { trace, propagation } from '@opentelemetry/api'; // Anti-pattern: Injecting sensitive/huge data into baggage, failing to record attributes locally, // and relying on default probabilistic head-sampling that drops failing error traces. export async function handleUserRequest(req: any) { const tracer = trace.getTracer('user-service'); let ctx = propagation.getBaggage(propagation.extract(req.headers)); // Storing PII and bulky auth tokens directly into downstream HTTP headers ctx = propagation.setBaggage( ctx, propagation.createBaggage({ authToken: { value: req.headers.authorization }, userProfile: { value: JSON.stringify(req.user) } }) ); return tracer.startActiveSpan('processRequest', async (span) => { try { await processBusinessLogic(req); } catch (err: any) { // Head sampler already made a retain/drop decision; error may never reach backend span.recordException(err); throw err; } finally { span.end(); } }); } ``` #### Production Standard (Correct) > **Standard**: Limits baggage to strict operational keys, excludes PII, and mirrors critical baggage entries onto local span attributes so that downstream OpenTelemetry Collector tail-based sampling rules can route and retain 100% of error or high-tier tenant traces. ```typescript import { trace, propagation, SpanStatusCode } from '@opentelemetry/api'; const ALLOWED_BAGGAGE_KEYS = new Set(['tenant.tier', 'routing.region']); export async function handleUserRequest(req: any) { const tracer = trace.getTracer('user-service'); const parentContext = propagation.extract(trace.setSpan(ctx, trace.getActiveSpan()!), req.headers); const incomingBaggage = propagation.getBaggage(parentContext); // Maintain low-cardinality metadata without PII let updatedBaggage = incomingBaggage ?? propagation.createBaggage({}); if (req.user?.tier) { updatedBaggage = updatedBaggage.setEntry('tenant.tier', { value: req.user.tier }); } const contextWithBaggage = propagation.setBaggage(parentContext, updatedBaggage); return tracer.startActiveSpan('processRequest', {}, contextWithBaggage, async (span) => { try { // Explicitly bridge baggage to local span attributes for tail-sampler visibility const tenantTier = updatedBaggage.getEntry('tenant.tier')?.value; if (tenantTier) { span.setAttribute('tenant.tier', tenantTier); } await processBusinessLogic(req); span.setStatus({ code: SpanStatusCode.OK }); } catch (err: any) { span.recordException(err); span.setStatus({ code: SpanStatusCode.ERROR, message: err.message }); span.setAttribute('error.severity', 'critical'); throw err; } finally { span.end(); } }); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: OpenTelemetry Distributed Baggage & Tail-Based Sampling Standard

OpenTelemetry Distributed Baggage & Tail-Based Sampling Standard defines an industrial-grade behavioral standard for devops engineering. Mandates strict separation between transient span attributes and distributed W3C baggage, enforcing baggage hygiene to prevent header bloat and PII leakage across RPC boundaries. Pairs contextual baggage propagation with tail-based OpenTelemetry Collector sampling configurations to guarantee 100% trace capture for critical errors and high-tier tenants while suppressing routine high-volume spans. 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: Overloading W3C Baggage with Unsanitized PII and Relying on Naive Head-Based Sampling for Error Paths 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	Overloading W3C Baggage with Unsanitized PII and Relying on Naive Head-Based Sampling for Error Paths	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 sanitize W3C Baggage and restrict keys to low-cardinality operational metadata (e.g., `tenant.tier`, `account.id`), strictly prohibiting PII, large payloads, or secrets.

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.