Skip to main content
Sampling determines whether a trace should be collected and recorded by your tracing system. The sampled flag is a single bit in the traceparent flags field that controls this behavior.

​
Understanding Sampling

The sampled flag (FLAG_SAMPLE) indicates whether the trace should be recorded:
  • 1 (sampled) - The trace should be collected and recorded
  • 0 (not sampled) - The trace should be dropped
By default, traceparent.make() creates traces with the sampled flag set to 1.
Sampling decisions should be made as early as possible in the trace and propagated to all downstream services to ensure consistent behavior.

​
Checking Sample Status

Use is_sampled() to check if a trace is currently being sampled: 
import * as traceparent from 'tctx/traceparent';

const parent = traceparent.parse(request.headers.traceparent);

if (traceparent.is_sampled(parent)) {
  // Trace is being recorded
  console.log('This trace will be collected');
} else {
  // Trace is not being recorded
  console.log('This trace will be dropped');
}

​
Enabling Sampling

Use sample() to enable sampling on a traceparent:
1

Parse or create a traceparent

import * as traceparent from 'tctx/traceparent';

const parent = traceparent.parse(request.headers.traceparent) || traceparent.make();
2

Apply sampling decision

traceparent.sample(parent);
This sets the sampled flag bit using bitwise OR:
parent.flags |= FLAG_SAMPLE; // Sets bit to 1
3

Propagate to downstream services

fetch('/downstream', {
  headers: {
    traceparent: parent.child(),
  },
});
According to the W3C specification, you should create a child span (using .child()) before changing the sampling decision to properly reflect the decision point in the trace hierarchy.

​
Disabling Sampling

Use unsample() to disable sampling on a traceparent: 
import * as traceparent from 'tctx/traceparent';

const parent = traceparent.parse(request.headers.traceparent);

// Decide not to sample this trace
traceparent.unsample(parent);

fetch('/downstream', {
  headers: {
    traceparent: parent.child(),
  },
});
This clears the sampled flag bit using bitwise AND with NOT: 
parent.flags &= ~FLAG_SAMPLE; // Sets bit to 0

​
Sampling Strategies

Here are common sampling strategies you can implement: 
import * as traceparent from 'tctx/traceparent';

const SAMPLE_RATE = 0.1; // Sample 10% of traces

function shouldSample(): boolean {
  return Math.random() < SAMPLE_RATE;
}

export async function handler(request: Request) {
  const parent = traceparent.parse(request.headers.traceparent) || traceparent.make();
  
  // Apply sampling decision
  if (shouldSample()) {
    traceparent.sample(parent);
  } else {
    traceparent.unsample(parent);
  }
  
  // Continue with request
  return fetch('/downstream', {
    headers: { traceparent: parent.child() },
  });
}

​
API Reference

​
sample
(id: Traceparent) => void
Modifies the flags of a Traceparent to enable the sampled flag bit.
import * as traceparent from 'tctx/traceparent';

const parent = traceparent.make();
traceparent.sample(parent);
​
unsample
(id: Traceparent) => void
Modifies the flags of a Traceparent to disable the sampled flag bit.
import * as traceparent from 'tctx/traceparent';

const parent = traceparent.make();
traceparent.unsample(parent);
​
is_sampled
(id: Traceparent) => boolean
Returns whether the traceparent is currently being sampled.
import * as traceparent from 'tctx/traceparent';

const parent = traceparent.make();
console.log(traceparent.is_sampled(parent)); // true

traceparent.unsample(parent);
console.log(traceparent.is_sampled(parent)); // false

​
Best Practices

Create child spans before sampling decisions

Per the W3C spec, call .child() before modifying sampling flags:
const child = parent.child();
traceparent.sample(child);

Make decisions early

Sampling decisions should be made as early as possible in the trace to avoid wasting resources on unsampled traces.

Document your strategy

Clearly document your sampling strategy so all teams understand why certain traces are collected or dropped.

Monitor sample rates

Track the percentage of sampled traces to ensure your strategy aligns with your tracing system’s capacity and budget.
The FLAG_SAMPLE constant is available for direct bit manipulation if needed:
import { FLAG_SAMPLE } from 'tctx/traceparent';
console.log(FLAG_SAMPLE); // 0b00000001

Producer/Consumer Pattern

Learn how to propagate trace contexts

Trace Flags

Understand all available trace flags

Build docs developers (and LLMs) love

Get started for freeTalk to us