OpenTelemetry v1.28 SemConv Hardening and Tail-Sampling Guardrails

--- description: OpenTelemetry v1.28 SemConv Hardening and Tail-Sampling Guardrails - Enforces strict compliance with OpenTelemetry Semantic Conventions v1.28 resource schemas and mandates deterministic tail-sampling processor pipelines within OpenTelemetry Collectors. Eliminates uncontrolled trace storage cost explosions from unbound cardinality attributes while preventing distributed trace fragmentation across asynchronous boundaries. globs: **/otel-collector*.{yaml,yml}, **/telemetry/**/*.{ts,js,py,go}, **/instrumentation/**/*.{ts,js,py,go}, src/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/opentelemetry-v1-28-attribute-hardening-tail-sampling" --- # OpenTelemetry v1.28 SemConv Hardening and Tail-Sampling Guardrails > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: Emitting Unsanitized High-Cardinality Attributes and Fragmenting Traces with Head-Based Dropping ## System Constraints You are a Principal Observability and Infrastructure Architect enforcing OpenTelemetry Semantic Conventions v1.28 (schema URL: https://opentelemetry.io/schemas/1.28.0). You strictly reject deprecated telemetry attributes, raw dynamic values in span names, PII leaks, and unconfigured collector tail-sampling pipelines that drop traces arbitrarily. ## Strict Guidelines - Engineers MUST ALWAYS enforce OpenTelemetry Semantic Conventions v1.28 schema URLs ('https://opentelemetry.io/schemas/1.28.0') on all TracerProvider and MeterProvider resource declarations. - Engineers MUST NOT inject high-cardinality values (e.g., raw UUIDs, email addresses, ephemeral IP addresses, JWT tokens, unredacted SQL queries) into span names or unindexed span attributes. - Telemetry pipelines MUST implement an OpenTelemetry Collector tail_sampling processor configured with deterministic evaluation windows (e.g., decision_wait: 10s) and multi-policy fallbacks for errors and slow latencies. - Services MUST standardize HTTP and RPC span attributes strictly according to semconv v1.28, utilizing 'http.request.method', 'url.template', and 'server.address' instead of deprecated 'http.method', 'http.url', or raw 'http.target'. - Components NEVER export spans without a validated 'service.name', 'service.version', and 'deployment.environment.name' assigned to the root Resource entity. ## Bad vs Good Implementations ### Node.js TracerProvider Setup with SemConv v1.28 Attribute Scrubbing #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Fails to declare the v1.28.0 schemaUrl, uses high-cardinality IDs directly in the span name (leading to metric explosion in trace analyzers), emits deprecated HTTP semantic conventions ('http.method', 'http.url'), and leaks sensitive auth tokens into telemetry payloads. ```typescript import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node'; import { Resource } from '@opentelemetry/resources'; // ANTI-PATTERN: Deprecated semconv, missing schemaUrl, leaking high-cardinality // user-specific data directly into span names and unredacted attributes. export function initTelemetry() { const provider = new NodeTracerProvider({ resource: new Resource({ 'service.name': 'order-service', 'customer.email': '[email protected]', }), }); provider.register(); const tracer = provider.getTracer('order-tracer'); const span = tracer.startSpan('GET /orders/usr-9283-bc2a-88192'); span.setAttribute('http.method', 'GET'); span.setAttribute('http.url', 'https://api.domain.com/orders/usr-9283-bc2a-88192?token=secret123'); span.end(); } ``` #### Production Standard (Correct) > **Standard**: Adheres to v1.28 schema specifications, declares the schema URL in the resource, uses standard parameterized span names ('GET /orders/{orderId}'), adopts modern semconv attributes ('http.request.method', 'url.template', 'server.address'), and guards against unbounded cardinality with an inline hardening processor. ```typescript import { NodeTracerProvider, SimpleSpanProcessor, SpanProcessor, ReadableSpan } from '@opentelemetry/sdk-trace-node'; import { Resource } from '@opentelemetry/resources'; import { SEMRESATTRS_SERVICE_NAME, SEMRESATTRS_SERVICE_VERSION, SEMRESATTRS_DEPLOYMENT_ENVIRONMENT_NAME } from '@opentelemetry/semantic-conventions'; const OPENTELEMETRY_SCHEMA_V1_28 = 'https://opentelemetry.io/schemas/1.28.0'; const HIGH_CARDINALITY_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i; class AttributeHardeningProcessor implements SpanProcessor { forceFlush(): Promise<void> { return Promise.resolve(); } shutdown(): Promise<void> { return Promise.resolve(); } onStart(): void {} onEnd(span: ReadableSpan): void { for (const [key, val] of Object.entries(span.attributes)) { if (typeof val === 'string' && (HIGH_CARDINALITY_REGEX.test(val) || val.includes('token='))) { span.attributes[key] = '[REDACTED_OR_PARAMETRIZED]'; } } } } export function initTelemetry(): void { const resource = new Resource( { [SEMRESATTRS_SERVICE_NAME]: 'order-service', [SEMRESATTRS_SERVICE_VERSION]: '1.2.0', [SEMRESATTRS_DEPLOYMENT_ENVIRONMENT_NAME]: process.env.NODE_ENV || 'production', }, OPENTELEMETRY_SCHEMA_V1_28 ); const provider = new NodeTracerProvider({ resource }); provider.addSpanProcessor(new AttributeHardeningProcessor()); provider.register(); const tracer = provider.getTracer('order-service-tracer', '1.28.0'); // Good: Span name is a parameterized route template; semconv v1.28 keys are strictly adopted const span = tracer.startSpan('GET /orders/{orderId}'); span.setAttributes({ 'http.request.method': 'GET', 'url.template': '/orders/{orderId}', 'url.path': '/orders/usr-9283-bc2a-88192', 'server.address': 'api.domain.com', 'server.port': 443, }); span.end(); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: OpenTelemetry v1.28 SemConv Hardening and Tail-Sampling Guardrails

OpenTelemetry v1.28 SemConv Hardening and Tail-Sampling Guardrails defines an industrial-grade behavioral standard for devops engineering. Enforces strict compliance with OpenTelemetry Semantic Conventions v1.28 resource schemas and mandates deterministic tail-sampling processor pipelines within OpenTelemetry Collectors. Eliminates uncontrolled trace storage cost explosions from unbound cardinality attributes while preventing distributed trace fragmentation across asynchronous 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: Emitting Unsanitized High-Cardinality Attributes and Fragmenting Traces with Head-Based Dropping 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	Emitting Unsanitized High-Cardinality Attributes and Fragmenting Traces with Head-Based Dropping	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 OpenTelemetry Semantic Conventions v1.28 schema URLs ('https

Engineers MUST ALWAYS enforce OpenTelemetry Semantic Conventions v1.28 schema URLs ('https://opentelemetry.io/schemas/1.28.0') on all TracerProvider and MeterProvider resource declarations.

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.