OpenTelemetry Semantic Conventions and Cardinality Quarantine Standard

--- description: OpenTelemetry Semantic Conventions and Cardinality Quarantine Standard - Enforces deterministic attribute bounds, strict baggage allowlisting, and automated redaction of dynamic high-cardinality values across OpenTelemetry distributed tracing pipelines. Prevents backend APM ingest denial-of-service, memory exhaustion, and runaway indexing costs by quarantining unbounded parameters at instrumentation boundaries. globs: src/**/*.ts, src/**/*.js, telemetry/**/*.ts, instrumentation/**/*.ts, collector/**/*.yaml alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/opentelemetry-cardinality-quarantine-guardrail" --- # OpenTelemetry Semantic Conventions and Cardinality Quarantine Standard > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: Unbounded Runtime Baggage and Direct Ingestion of High-Cardinality Variables into Span Attributes ## System Constraints You are a Principal Observability and Infrastructure Architect enforcing OpenTelemetry Semantic Conventions Context Cardinality Quarantine. You mandate deterministic limits on trace attributes and context propagation. Reject all code that sets unparameterized routes, raw URLs with UUIDs/emails, unbounded baggage propagation, or missing SpanLimits in NodeTracerProvider initialization. ## Strict Guidelines - Engineers MUST ALWAYS configure deterministic SpanLimits (attributeCountLimit, attributeValueLengthLimit) during TracerProvider registration. - Engineers MUST ALWAYS enforce strict parameterized route patterns (e.g., http.route = '/users/:id') rather than injecting raw URLs with UUIDs or query strings into span attributes. - Engineers MUST NOT propagate arbitrary client headers, raw JWT claims, or variable user payloads directly into W3C Baggage context. - Code SHOULD implement an explicit CardinalityQuarantineSpanProcessor to truncate, redact, or drop attributes exceeding safe cardinality thresholds before exporter dispatch. - Services MUST quarantine baggage entries exceeding 128 bytes per key or 2048 bytes in aggregate, rejecting un-whitelisted baggage keys at service entrypoints. - Components NEVER store PII, session tokens, or unhashed internal identifiers in standard OpenTelemetry semantic convention tags. ## Bad vs Good Implementations ### Span Limits and Cardinality Quarantine Implementation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The provider lacks deterministic SpanLimits, allowing unbounded attribute counts and lengths. The span directly attaches high-cardinality identifiers (UUID in raw URL, email, full payload), and unvetted authorization tokens are inserted into distributed Baggage, risking downstream memory bloat and tracing backend index explosion. ```typescript import { trace, propagation } from '@opentelemetry/api'; import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node'; import { SimpleSpanProcessor, ConsoleSpanExporter } from '@opentelemetry/sdk-trace-base'; // ANTI-PATTERN: No SpanLimits configured; vulnerable to memory exhaustion and payload DOS const provider = new NodeTracerProvider(); provider.addSpanProcessor(new SimpleSpanProcessor(new ConsoleSpanExporter())); provider.register(); const tracer = trace.getTracer('user-service'); export function handleRequest(req: any) { // ANTI-PATTERN: Direct injection of unbounded high-cardinality URI and raw parameters const span = tracer.startSpan('http_request'); span.setAttribute('http.url', req.originalUrl); // e.g., /api/v1/users/550e8400-e29b-41d4-a716-446655440000?search=confidential span.setAttribute('user.email', req.user.email); span.setAttribute('raw.payload', JSON.stringify(req.body)); // ANTI-PATTERN: Unbounded Baggage propagation const baggage = propagation.createBaggage({ jwt: req.headers['authorization'] ?? '', requestId: req.headers['x-request-id'] ?? '' }); propagation.setBaggage(propagation.extract(trace.setSpan(propagation.context.active(), span), req.headers), baggage); span.end(); } ``` #### Production Standard (Correct) > **Standard**: Configures strict SpanLimits on the NodeTracerProvider to bound payload volume. Implements an explicit CardinalityQuarantineProcessor, utilizes parameterized semantic convention attributes ('http.route') instead of dynamic raw URLs, and strictly allowlists and truncates context baggage entries. ```typescript import { trace, propagation, Context, Span } from '@opentelemetry/api'; import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node'; import { BatchSpanProcessor, ConsoleSpanExporter, SpanProcessor, ReadableSpan } from '@opentelemetry/sdk-trace-base'; import { SEMRESATTRS_SERVICE_NAME } from '@opentelemetry/semantic-conventions'; import { Resource } from '@opentelemetry/resources'; // Safe baggage allowlist const ALLOWED_BAGGAGE_KEYS = new Set(['tenant.id', 'client.version', 'region']); const MAX_BAGGAGE_VAL_LEN = 64; class CardinalityQuarantineProcessor implements SpanProcessor { forceFlush(): Promise<void> { return Promise.resolve(); } shutdown(): Promise<void> { return Promise.resolve(); } onStart(span: Span, _parentContext: Context): void { // Mutate or safeguard at start if required } onEnd(span: ReadableSpan): void { // Quarantine / Scrub attributes post-execution before exporter serialization const attrs = span.attributes; if (attrs['http.url']) { delete (attrs as Record<string, unknown>)['http.url']; } } } // PRODUCTION FIX: Hard deterministic limits set on span count and attribute size const provider = new NodeTracerProvider({ resource: new Resource({ [SEMRESATTRS_SERVICE_NAME]: 'user-service' }), spanLimits: { attributeCountLimit: 64, attributeValueLengthLimit: 256, eventCountLimit: 32 } }); provider.addSpanProcessor(new CardinalityQuarantineProcessor()); provider.addSpanProcessor(new BatchSpanProcessor(new ConsoleSpanExporter())); provider.register(); const tracer = trace.getTracer('user-service'); export function handleRequest(req: any) { const span = tracer.startSpan('http_request', { attributes: { // Conform to OTel Semantic Conventions using parameterized route 'http.method': req.method, 'http.route': '/api/v1/users/:id', 'http.status_code': 200 } }); // PRODUCTION FIX: Sanitized and allowlist-quarantined Baggage propagation const safeEntries: Record<string, { value: string }> = {}; for (const [key, val] of Object.entries(req.headers)) { if (ALLOWED_BAGGAGE_KEYS.has(key) && typeof val === 'string') { safeEntries[key] = { value: val.slice(0, MAX_BAGGAGE_VAL_LEN) }; } } const baggage = propagation.createBaggage(safeEntries); propagation.setBaggage(trace.setSpan(propagation.context.active(), span), baggage); span.end(); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: OpenTelemetry Semantic Conventions and Cardinality Quarantine Standard

OpenTelemetry Semantic Conventions and Cardinality Quarantine Standard defines an industrial-grade behavioral standard for devops engineering. Enforces deterministic attribute bounds, strict baggage allowlisting, and automated redaction of dynamic high-cardinality values across OpenTelemetry distributed tracing pipelines. Prevents backend APM ingest denial-of-service, memory exhaustion, and runaway indexing costs by quarantining unbounded parameters at instrumentation boundaries. 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 Runtime Baggage and Direct Ingestion of High-Cardinality Variables into Span Attributes 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 Runtime Baggage and Direct Ingestion of High-Cardinality Variables into Span Attributes	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 configure deterministic SpanLimits (attributeCountLimit, attributeValueLengthLimit) during TracerProvider registration.

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.