Exemplars - KodeKloud

Exemplars are contextual breadcrumbs that metrics can leave behind to connect numeric measurements with trace data. Rather than being random samples, exemplars are representative specimens captured at the exact moment a measurement occurs. They let you attach additional context—most commonly trace IDs and span IDs—to a specific metric observation, making it possible to jump directly from a metric anomaly to the distributed trace that produced it.

The image explains exemplars as sample data points associated with specific time series in metrics, highlighting their role in capturing the context of measurements for enabling correlation of metric data with trace data.

Why exemplars matter

They enrich metrics with non-metric context (trace IDs, span IDs, and filtered attributes), turning raw numbers into actionable signals.
The primary use case is linking a metric data point directly to the trace that was active when the measurement occurred, enabling rapid investigation.
Exemplars speed up root-cause analysis by letting you navigate from an outlier metric point straight to the trace details.
They improve observability by providing the “why” behind metric changes, not just the “what.”

What an exemplar contains

Value: the measurement itself (e.g., the value passed to counter.Add() or histogram.Record()).
Timestamp: the exact time the measurement was recorded.
Filtered attributes: labels that remain after any views/filters are applied to reduce noise while preserving useful context.
Trace context: the trace ID and span ID linking the measurement to a distributed trace.

The image illustrates four types of information an exemplar carries: Value, Timestamp, Filtered Attributes, and Trace Context, each with a brief description.

Quick reference: exemplar components

Element	Description	Example
Value	The numeric measurement recorded	`histogram.Record(245)`
Timestamp	When the measurement occurred	`2026-07-15T12:34:56Z`
Filtered attributes	Labels retained after views/filters	`service="checkout", region="us-east-1"`
Trace context	Trace ID and span ID linking to the trace	`trace_id=4bf92f3577b34da6a3ce929d0e0e4736`

Enabling exemplars (C# / .NET) Below is a typical .NET MeterProvider configuration that enables trace-based exemplars and exports metrics to both the console and an OTLP collector endpoint:

using var meterProvider = Sdk.CreateMeterProviderBuilder()
    .SetResourceBuilder(resource)
    .AddMeter("MyCompany.MyProduct.MyLibrary")
    .SetExemplarFilter(ExemplarFilterType.TraceBased) // Enable trace-based exemplars
    .AddConsoleExporter() // Export metrics to console for debugging
    .AddOtlpExporter(options => options.Endpoint = new Uri("http://localhost:4317"))
    .Build();

Setting SetExemplarFilter(ExemplarFilterType.TraceBased) tells the OpenTelemetry SDK to attach trace and span IDs to metric measurements when a trace is active, creating exemplars automatically.

How exemplars are captured and surfaced

Capture: When a metric is recorded and there is an active trace, the metrics SDK captures the trace ID and span ID and attaches them to that measurement as an exemplar.
Export: Exemplars are exported along with metric data to your observability backend (for example, an OTLP collector).
Visualization: The observability backend (the visualization layer) links and stitches metrics, traces, and logs so that exemplars can be displayed as clickable markers on charts. Clicking an exemplar usually reveals the trace ID and a link to the full trace.

Using exemplars with Prometheus and UI integrations In dashboards that plot histograms or other metrics (e.g., HTTP latency), exemplars appear as individual clickable markers. With exemplars enabled, clicking a plotted data point may provide the trace link for the exact request that produced it. Example PromQL query to compute a percentile from an HTTP server histogram:

histogram_quantile(
  0.75,
  sum by (le)(
    rate(http_server_duration_milliseconds_bucket{job="exemplar"}[5m])
  )
)

When exemplars are present, many UIs will show exemplar markers on the plotted series. Clicking one of those markers lets you follow the exemplar link to the trace that generated that measurement. Practical benefits

Correlation: Associate trace and attribute context with metric samples to get immediate context for metric anomalies.
Faster troubleshooting: Jump from an anomalous metric point to the exact trace that produced it.
Contextual observability: Move beyond isolated metrics to an integrated view of metrics, traces, and logs.
Efficiency: Reduce time-to-resolution and improve resource utilization through clearer root-cause insights.

The image explains the importance of exemplars, highlighting their use in associating non-metric data with metric data, linking metrics to active traces, efficient troubleshooting, and improving contextual observability.

How exemplars are created (step-by-step)

Configure the SDK to enable exemplar filtering (e.g., trace-based exemplars).
Record metrics in your instrumentation while traces are active.
The SDK captures trace context for those measurements and emits exemplars with the metric data.
The observability backend receives metrics and traces, stitches them together, and renders exemplar markers in the UI.

Summary

Exemplars augment numeric metrics with trace and attribute context, providing a direct link between metrics and traces.
They accelerate root-cause analysis by allowing you to jump from a metric anomaly to the exact trace that produced it.
Exemplars enhance observability and reduce time-to-resolution by revealing why a metric value occurred, not just that it occurred.

The image lists three key benefits of exemplars: augmenting metrics with traces and logs, accelerating root cause analysis, and optimizing resource utilization.

Watch Video

Metrics SDK Lifecycle APIs and Views

Demo Metrics Instrumentation