OpenTelemetry Exponential Histogram Bucketing & Cardinality Guardrail

Q: How does adopting this rule prevent AI hallucinations?

This rule explicitly declares what the AI must avoid (Unbounded Explicit Boundary Histograms and Unsanitized Attribute Cardinality Inducing Memory Leaks and Percentile Distortion) 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 Exponential Histogram Bucketing & Cardinality Guardrail

Enforces Base-2 Exponential Bucket Histograms across OpenTelemetry MetricReaders to guarantee constant-relative-error latency tracking while capping memory consumption. Prohibits explicit boundary histograms on microsecond/millisecond latency metrics that cause unbounded memory overhead or inaccurate tail percentiles. Mandates strict cardinality bounding per instrument and view-level aggregation controls to defend against distributed denial-of-memory under high-throughput label variations.

--- description: OpenTelemetry Exponential Histogram Bucketing & Cardinality Guardrail - Enforces Base-2 Exponential Bucket Histograms across OpenTelemetry MetricReaders to guarantee constant-relative-error latency tracking while capping memory consumption. Prohibits explicit boundary histograms on microsecond/millisecond latency metrics that cause unbounded memory overhead or inaccurate tail percentiles. Mandates strict cardinality bounding per instrument and view-level aggregation controls to defend against distributed denial-of-memory under high-throughput label variations. globs: src/**/telemetry.{ts,js}, src/**/metrics.{ts,js}, src/**/instrumentation.{ts,js}, src/**/*otel*.{ts,js} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/otel-exponential-histogram-bucketing-standard" --- # OpenTelemetry Exponential Histogram Bucketing & Cardinality Guardrail > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: Unbounded Explicit Boundary Histograms and Unsanitized Attribute Cardinality Inducing Memory Leaks and Percentile Distortion ## System Constraints You are a Principal Observability and Performance Architect enforcing the OpenTelemetry Metrics Exponential Histogram Bucketing Standard. You must mandate Exponential Bucket Histograms with strict scale and bucket-limit invariants for latency and duration distributions. Enforce strict label sanitization to prevent cardinality explosions, require aggregation views with bounded max_buckets (≤160), and reject explicit boundary histograms for high-dynamic-range measurements. ## Strict Guidelines - Engineers MUST ALWAYS configure View instances with ExponentialHistogramAggregation (or InstrumentSelector targeting Histograms) for duration and latency measurements. - Engineers MUST configure 'maxBuckets' with a bounded upper limit (recommended <= 160 buckets) and a target scale (scale between 3 and 20) to maintain relative error below 6% while strictly budgeting memory. - Engineers MUST NOT use ExplicitBucketHistogramAggregation for wide dynamic range metrics (e.g., RPC latency, HTTP response times), as it incurs static resolution bias and linear memory penalties per label combination. - Services MUST sanitize, filter, or hash metric attributes before recording, explicitly disallowing high-cardinality values such as user IDs, UUIDs, trace IDs, raw URLs, or query parameters in metric labels. - Services MUST register a MetricReader with cardinality limits enabled (e.g., CardinalityLimitSelector or maximum active streams) to prevent Out-Of-Memory (OOM) crashes during distributed traffic surges. ## Bad vs Good Implementations ### Configuring Exponential Histogram View with Cardinality Bounds vs Unbounded Explicit Boundaries #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Using ExplicitBucketHistogramAggregation allocates fixed-size arrays per stream and severely truncates tail-latency accuracy. Recording un-sanitized labels (UUIDs, raw routes) causes an unbounded explosion of distinct metric streams, quickly leading to heap exhaustion and telemetry pipeline dropping. ```typescript import { MeterProvider, ExplicitBucketHistogramAggregation, View, InstrumentType } from '@opentelemetry/sdk-metrics'; import { OTLPMetricExporter } from '@opentelemetry/exporter-metrics-otlp-http'; import { PeriodicExportingMetricReader } from '@opentelemetry/sdk-metrics'; // ANTI-PATTERN: Default or explicit buckets with 20+ boundaries, no label filtering, // leading to exponential memory usage when combined with high-cardinality attributes. const meterProvider = new MeterProvider({ readers: [ new PeriodicExportingMetricReader({ exporter: new OTLPMetricExporter(), exportIntervalMillis: 10000, }), ], views: [ new View({ instrumentType: InstrumentType.HISTOGRAM, // Explicit linear/arbitrary boundaries fail to capture dynamic tail latency accurately aggregation: new ExplicitBucketHistogramAggregation([ 0, 5, 10, 25, 50, 75, 100, 250, 500, 750, 1000, 2500, 5000, 10000 ]), }), ], }); const meter = meterProvider.getMeter('http-service'); const latencyHistogram = meter.createHistogram('http.server.duration'); // Bad: Injecting high-cardinality parameters straight into metric labels export function recordRequestDuration(durationMs: number, pathWithParams: string, userId: string) { latencyHistogram.record(durationMs, { 'http.route': pathWithParams, // e.g. /users/123e4567-e89b-12d3-a456-426614174000 'user.id': userId, }); } ``` #### Production Standard (Correct) > **Standard**: ExponentialHistogramAggregation dynamically adjusts scale to fit latency ranges with constant relative error. Bounding maxBuckets to 160 caps the maximum memory per time-series. The View explicitly defines 'attributeKeys', stripping out user IDs and raw dynamic URLs before streams are allocated. ```typescript import { MeterProvider, ExponentialHistogramAggregation, View, InstrumentType } from '@opentelemetry/sdk-metrics'; import { OTLPMetricExporter } from '@opentelemetry/exporter-metrics-otlp-http'; import { PeriodicExportingMetricReader } from '@opentelemetry/sdk-metrics'; // PRODUCTION STANDARD: Bounded Base-2 Exponential Histogram View // Max buckets = 160 ensures relative error is mathematically bounded <= ~4.4% // while bounding memory usage per active stream to hundreds of bytes. const meterProvider = new MeterProvider({ readers: [ new PeriodicExportingMetricReader({ exporter: new OTLPMetricExporter(), exportIntervalMillis: 15000, }), ], views: [ new View({ instrumentName: '*.duration*', instrumentType: InstrumentType.HISTOGRAM, aggregation: new ExponentialHistogramAggregation(160, 20), // Whitelist low-cardinality dimensions to prevent label explosion attributeKeys: ['http.status_code', 'http.method', 'http.route'], }), ], }); const meter = meterProvider.getMeter('http-service'); const latencyHistogram = meter.createHistogram('http.server.duration', { unit: 'ms', description: 'HTTP inbound request latency distribution', }); // Good: Parametrized route template and filtered dimension keys export function recordRequestDuration(durationMs: number, parameterizedRoute: string, statusCode: number) { latencyHistogram.record(durationMs, { 'http.route': parameterizedRoute, // e.g. /users/:id 'http.status_code': statusCode, 'http.method': 'GET', }); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: OpenTelemetry Exponential Histogram Bucketing & Cardinality Guardrail

OpenTelemetry Exponential Histogram Bucketing & Cardinality Guardrail defines an industrial-grade behavioral standard for devops engineering. Enforces Base-2 Exponential Bucket Histograms across OpenTelemetry MetricReaders to guarantee constant-relative-error latency tracking while capping memory consumption. Prohibits explicit boundary histograms on microsecond/millisecond latency metrics that cause unbounded memory overhead or inaccurate tail percentiles. Mandates strict cardinality bounding per instrument and view-level aggregation controls to defend against distributed denial-of-memory under high-throughput label variations. 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 Explicit Boundary Histograms and Unsanitized Attribute Cardinality Inducing Memory Leaks and Percentile Distortion 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 Explicit Boundary Histograms and Unsanitized Attribute Cardinality Inducing Memory Leaks and Percentile Distortion	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 View instances with ExponentialHistogramAggregation (or InstrumentSelector targeting Histograms) for duration and latency measurements.

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.