Exemplar Linking Strategy
Exemplar linking attaches a trace ID to the metric bucket that triggered it, so a dashboard spike links directly to a representative trace, closing the gap between aggregate and instance.
Definition
Exemplar linking is the observability practice of storing, alongside a histogram bucket or counter, a reference to a recent trace that fell into that bucket, so that when a dashboard shows a spike in p99 latency the operator can click through to a trace that exemplifies the spike and begin diagnosis without a separate query.
Context and scope
Applied in Prometheus exemplars, OpenTelemetry, and any metrics system that integrates with tracing and wants to bridge the aggregate-to-instance gap.
Common misconceptions
- Exemplars are just sampled traces — they are sampled traces linked to the metric bucket they represent; the link is the value, not the trace itself
- Every metric should have an exemplar — exemplars have storage cost; they should be on the metrics where the bridge to a trace is actionable
Anti-patterns
- Attaching an exemplar to every increment of a counter, storing a trace reference per increment and overwhelming storage
- Linking an exemplar to a trace that does not actually fall in the bucket, misleading the operator who clicks through
Related concepts
Authoritative source
https://prometheus.io/docs/prometheus/latest/feature_exemplars/
What it is
Exemplar linking is the observability practice of storing, alongside a histogram bucket or counter, a reference to a recent trace that fell into that bucket, so that when a dashboard shows a spike in p99 latency the operator can click through to a trace that exemplifies the spike and begin diagnosis without a separate query. Applied in Prometheus exemplars, OpenTelemetry, and any metrics system that integrates with tracing and wants to bridge the aggregate-to-instance gap. The goal is not to collect all data but to be able to answer the question you did not think to ask in advance — which requires high-cardinality labels and exemplars that link traces to the metric that triggered them.
How it works
Three signals compose: metrics aggregate over time, traces preserve causality across boundaries, and logs carry the unstructured detail. Sampling is adaptive — head sampling for known-interesting paths, tail sampling to retain slow or error traces at a fixed budget. Cardinality is controlled at the source, not the query, because a high-cardinality label explodes storage and makes dashboards unusable.
When to invest and pitfalls
Invest when mean time to detect matters — in production, at scale, with paying users. The pitfall is instrumenting everything and alerting on nothing: dashboards full of lines that no one reads, alerts that fire on noise and are then muted, leaving the real outage undetected. Symptom-based alerts on user-visible degradation outperform cause-based alerts on internal thresholds.