OpenTelemetry Exponential Histogram Aggregation and Exemplar Alignment Standard

--- description: OpenTelemetry Exponential Histogram Aggregation and Exemplar Alignment Standard - Enforces OpenTelemetry native exponential bucket histograms with dynamic scaling over static explicit boundaries to bound timeseries cardinality while preserving relative error guarantees across latency dynamic ranges. Mandates deterministic attachment of distributed trace contexts via OpenTelemetry exemplars instead of injecting high-cardinality identifiers into metric dimensions. globs: **/instrumentation/**/*.{ts,js,go,py}, **/telemetry/**/*.{ts,js,go,py}, **/metrics/**/*.{ts,js,go,py}, **/observability/**/*.{ts,js,go,py} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/otel-exponential-histogram-exemplar-alignment" --- # OpenTelemetry Exponential Histogram Aggregation and Exemplar Alignment Standard > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: Static Bucket Histogram Cardinality Explosion and Metric Dimension Contamination ## System Constraints You are a Principal Observability Architect enforcing OpenTelemetry native exponential histogram aggregation and strict exemplar-trace alignment. Mandate bounded storage footprints, low-cardinality metric dimensions, dynamic scaling exponential histograms, and context-attached exemplars. ## Strict Guidelines - Engineers MUST ALWAYS configure MeterProvider Views with ExponentialHistogramAggregation (setting maxSize and maxScale) for latency and duration distributions rather than ExplicitBucketHistogramAggregation. - Engineers MUST NEVER append unique or high-cardinality identifiers (such as user_id, order_id, tenant_id, trace_id, or IP addresses) directly as metric attributes/dimensions. - Engineers MUST configure an ExemplarFilter (such as TraceBasedExemplarFilter or AlwaysOnExemplarFilter) to bind TraceID and SpanID directly to bucketed histogram samples without multiplying timeseries streams. - Engineers MUST pass the active telemetry Context (`context.active()`) when invoking `histogram.record()` to ensure the exemplar reservoir deterministically samples and links the active trace. - Services MUST bound the exponential histogram `maxSize` to 160 buckets and clamp `maxScale` to 20 to balance dynamic range relative error (sub-5%) against transport serialization costs. - Telemetry views MUST explicitly filter out unbound labels before metrics leave memory using attribute processors or low-cardinality metric attribute allow-lists. ## Bad vs Good Implementations ### TypeScript: Explicit Bucket Explosion vs Exponential Histogram with Exemplars #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Creates static-bucket histograms with inaccurate dynamic tail precision, while injecting high-cardinality attributes (order.id, user.id, trace.id) directly into the metric timeseries. This causes massive memory spikes in the collector and tsdb storage index failure, while failing to use native exemplar infrastructure. ```typescript import { metrics, trace, context } from '@opentelemetry/api'; import { MeterProvider, ExplicitBucketHistogramAggregation, View } from '@opentelemetry/sdk-metrics'; const meterProvider = new MeterProvider(); const meter = meterProvider.getMeter('billing-service'); // ANTI-PATTERN: Fixed static bucket boundaries with poor dynamic resolution // Anti-pattern: High-cardinality data injected directly into metric attributes const latencyHistogram = meter.createHistogram('http.server.duration', { unit: 'ms', description: 'HTTP server execution latency', }); export async function handleRequest(req: Request) { const startTime = performance.now(); const activeSpan = trace.getActiveSpan(); try { await processOrder(req); } finally { const durationMs = performance.now() - startTime; // DISASTER: trace_id, order_id, user_id generate infinite unique timeseries permutations latencyHistogram.record(durationMs, { 'http.route': '/checkout', 'http.status_code': 200, 'order.id': req.headers.get('x-order-id') ?? 'unknown', 'user.id': req.headers.get('x-user-id') ?? 'anon', 'trace.id': activeSpan?.spanContext().traceId ?? 'none' }); } } ``` #### Production Standard (Correct) > **Standard**: Defines an ExponentialHistogramAggregation View bounding storage footprint while retaining arbitrary dynamic resolution. Lowers metric dimensions to strictly static, low-cardinality values, and uses the active context to sample exemplars (TraceID/SpanID) directly on individual bucket boundaries without causing timeseries cardinality explosion. ```typescript import { metrics, context } from '@opentelemetry/api'; import { MeterProvider, ExponentialHistogramAggregation, View, InstrumentType, AlwaysOnExemplarFilter, PeriodicExportingMetricReader } from '@opentelemetry/sdk-metrics'; // Configure MeterProvider with Native Exponential Histogram View and Exemplar Filter const meterProvider = new MeterProvider({ exemplarFilter: new AlwaysOnExemplarFilter(), views: [ new View({ instrumentName: 'http.server.duration', instrumentType: InstrumentType.HISTOGRAM, // MaxSize 160 with maxScale 20 provides sub-5% relative error across dynamic microsecond-to-minute ranges aggregation: new ExponentialHistogramAggregation(160, 20), // Explicitly allow-list low-cardinality metric attributes attributeKeys: ['http.route', 'http.request.method', 'http.response.status_code'] }) ] }); const meter = meterProvider.getMeter('billing-service'); const latencyHistogram = meter.createHistogram('http.server.duration', { unit: 'ms', description: 'HTTP server duration with exponential distribution and exemplar links', }); export async function handleRequest(req: Request) { const startTime = performance.now(); const activeContext = context.active(); try { await processOrder(req); } finally { const durationMs = performance.now() - startTime; // CORRECT: High-cardinality identifiers exist ONLY within active trace span; // metric dimensions remain bounded, and activeContext attaches trace context as an Exemplar latencyHistogram.record( durationMs, { 'http.route': '/checkout', 'http.request.method': 'POST', 'http.response.status_code': 200 }, activeContext ); } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: OpenTelemetry Exponential Histogram Aggregation and Exemplar Alignment Standard

OpenTelemetry Exponential Histogram Aggregation and Exemplar Alignment Standard defines an industrial-grade behavioral standard for devops engineering. Enforces OpenTelemetry native exponential bucket histograms with dynamic scaling over static explicit boundaries to bound timeseries cardinality while preserving relative error guarantees across latency dynamic ranges. Mandates deterministic attachment of distributed trace contexts via OpenTelemetry exemplars instead of injecting high-cardinality identifiers into metric dimensions. 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: Static Bucket Histogram Cardinality Explosion and Metric Dimension Contamination 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	Static Bucket Histogram Cardinality Explosion and Metric Dimension Contamination	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 MeterProvider Views with ExponentialHistogramAggregation (setting maxSize and maxScale) for latency and duration distributions rather than ExplicitBucketHistogramAggregation.

Engineers MUST ALWAYS configure MeterProvider Views with ExponentialHistogramAggregation (setting maxSize and maxScale) for latency and duration distributions rather than ExplicitBucketHistogramAggregation.

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.