OpenTelemetry Metric Exemplar Fixed-Reservoir Cardinality Bounding Standard

Q: How does adopting this rule prevent AI hallucinations?

This rule explicitly declares what the AI must avoid (Unbounded or Default Exemplar Allocation Under High Throughput Causing Heap Bloat and GC Pauses) 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 Metric Exemplar Fixed-Reservoir Cardinality Bounding Standard

--- description: OpenTelemetry Metric Exemplar Fixed-Reservoir Cardinality Bounding Standard - Enforces strict memory-safe boundaries on OpenTelemetry exemplar retention across high-throughput metrics pipelines. Mandates lock-free fixed-size circular reservoirs and trace-based exemplar filters to eliminate heap exhaustion caused by unbounded trace-metric exemplar linkage under high transaction volumes. 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-metric-exemplar-fixed-reservoir-bounding-standard" --- # OpenTelemetry Metric Exemplar Fixed-Reservoir Cardinality Bounding Standard > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: Unbounded or Default Exemplar Allocation Under High Throughput Causing Heap Bloat and GC Pauses ## System Constraints You are a Principal Engineer enforcing the OTel Metric Exemplar Fixed-Reservoir Cardinality Bounding Standard. You must mandate strict memory bounds, non-allocating circular buffers, and trace-state sampling filters on all OpenTelemetry metric exemplar pipelines. Reject any configuration using default unconstrained exemplar filters or unbounded retention under high throughput. ## Strict Guidelines - Engineers MUST ALWAYS configure an explicit `ExemplarFilter` (such as `TraceBasedExemplarFilter`) rather than accepting default `AlwaysSampleExemplarFilter` behavior in production environments. - Engineers MUST NOT allow unbounded memory growth in metric pipelines; all metric aggregators capturing exemplars MUST employ fixed-capacity circular reservoirs (e.g., bucket-aligned or limited reservoir size <= 1 per bucket/explicit count limit). - Code SHOULD enforce lock-free circular overwriting in custom exemplar reservoirs to prevent thread contention and stop memory growth under saturated traffic spikes. - Services MUST ensure that only sampled traces (e.g., `TraceFlags.SAMPLED`) produce metric exemplars, filtering out non-recording and un-sampled spans before exemplar capture. - Components NEVER store dynamic, high-cardinality metadata payloads inside metric exemplar attributes; exemplar attributes MUST be constrained strictly to trace identifiers (`trace_id`, `span_id`). ## Bad vs Good Implementations ### Configuring Metric Reader with Fixed-Capacity Exemplar Reservoir and Trace-Sampled Filter #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Defaulting or omitting explicit exemplar configuration enables continuous exemplar creation for every metric increment, holding span/trace references and unbounded context strings in memory during high-volume spikes, leading to Node.js / V8 OOM crashes. ```typescript import { MeterProvider, PeriodicExportingMetricReader } from '@opentelemetry/sdk-metrics'; import { OTLPMetricExporter } from '@opentelemetry/exporter-metrics-otlp-http'; // ANTI-PATTERN: Default configuration uses AlwaysSampleExemplarFilter and // unbounded / default reservoir setups that leak memory under 100k+ rps. const metricReader = new PeriodicExportingMetricReader({ exporter: new OTLPMetricExporter({ url: 'http://otel-collector:4318/v1/metrics' }), exportIntervalMillis: 10000, }); export const meterProvider = new MeterProvider({ readers: [metricReader], // Missing explicit exemplarFilter and bounded reservoir factory. // High-throughput traffic will retain trace references across every measurement, // causing severe heap allocation and catastrophic garbage collection pauses. }); ``` #### Production Standard (Correct) > **Standard**: Fences exemplar creation behind a strict `TraceFlags.SAMPLED` validation filter and pairs it with controlled explicit bucket aggregations. This bounds exemplar allocations to a predictable maximum memory envelope even under extreme ingress traffic. ```typescript import { MeterProvider, PeriodicExportingMetricReader, View, InstrumentType, ExplicitBucketHistogramAggregation } from '@opentelemetry/sdk-metrics'; import { OTLPMetricExporter } from '@opentelemetry/exporter-metrics-otlp-http'; import { TraceFlags, isSpanContextValid } from '@opentelemetry/api'; // Explicitly enforce trace-based exemplar filtering: // Only retain exemplars if the active span context is sampled. const traceBasedExemplarFilter = { shouldSample(value: number, timestamp: number, attributes: Record<string, unknown>, ctx: any): boolean { const spanContext = ctx ? isSpanContextValid(ctx) : null; return Boolean(spanContext && (spanContext.traceFlags & TraceFlags.SAMPLED) === TraceFlags.SAMPLED); } }; const metricReader = new PeriodicExportingMetricReader({ exporter: new OTLPMetricExporter({ url: 'http://otel-collector:4318/v1/metrics' }), exportIntervalMillis: 10000, }); export const meterProvider = new MeterProvider({ readers: [metricReader], views: [ // Constrain histogram cardinality and bucket allocation new View({ instrumentType: InstrumentType.HISTOGRAM, aggregation: new ExplicitBucketHistogramAggregation([0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10]), }) ], exemplarFilter: traceBasedExemplarFilter, }); ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: OpenTelemetry Metric Exemplar Fixed-Reservoir Cardinality Bounding Standard

OpenTelemetry Metric Exemplar Fixed-Reservoir Cardinality Bounding Standard defines an industrial-grade behavioral standard for devops engineering. Enforces strict memory-safe boundaries on OpenTelemetry exemplar retention across high-throughput metrics pipelines. Mandates lock-free fixed-size circular reservoirs and trace-based exemplar filters to eliminate heap exhaustion caused by unbounded trace-metric exemplar linkage under high transaction volumes. 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 or Default Exemplar Allocation Under High Throughput Causing Heap Bloat and GC Pauses 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 or Default Exemplar Allocation Under High Throughput Causing Heap Bloat and GC Pauses	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 an explicit `ExemplarFilter` (such as `TraceBasedExemplarFilter`) rather than accepting default `AlwaysSampleExemplarFilter` behavior in production environments.

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.