Course contentsShow
← System Design
Lesson 1256 of 1,91931. Observability: TracingFree lesson

Priority and Debug Sampling

Always sampling high-priority requests or traces marked for debugging; using headers to force tracing.

Priority and Debug Sampling

What you'll learn: How to force specific traces to always be sampled based on request priority or debugging flags, overriding normal sampling rates.


The Core Idea

Not all requests are created equal. While adaptive or head-based sampling might keep only 1% of normal traffic traces, you often need guaranteed visibility into critical transactions or when actively debugging a production issue. Priority and debug sampling lets you mark certain requests as "must trace" through special headers or flags, ensuring they're captured regardless of sampling rates.

Think of it like security fast-tracking at an airport: most passengers go through random selection, but VIPs or flagged individuals always get screened. Similarly, high-priority API calls or debug-flagged requests always generate complete traces.

How It Works

You implement this by checking incoming request headers or context before making sampling decisions:

Priority sampling: High-value transactions (premium users, checkout flows, critical B2B partners) carry a priority flag. Your instrumentation detects this and forces sampled=true.

Debug sampling: Engineers add a debug header (X-Trace-Debug: 1) to specific requests during investigation. The tracing system honors this flag and captures the full trace, often with additional detail (more span events, extra attributes).

The W3C Trace Context standard supports this through the sampled flag in the traceparent header, which downstream services must respect.

Common Pattern

if (request.headers['X-Priority'] === 'high' || 
    request.headers['X-Trace-Debug']) {
  forceSample = true;
}

This overrides whatever your head-based or adaptive sampler would have decided.

Key Takeaway: Priority and debug sampling ensures critical requests and debug sessions are always traced by using headers or flags to override normal sampling logic, giving you guaranteed visibility when it matters most.