@sophonz/session-based-sampler

OpenTelemetry sampler that decides per session instead of per trace.

한국어

The standard TraceIdRatioBasedSampler hashes the trace ID, so a 10% ratio keeps 10% of an individual user's traces — every session ends up partially recorded and no single session can be replayed end to end. This sampler hashes the RUM session ID instead, so a 10% ratio keeps 100% of the traces from 10% of sessions. The sessions you keep are complete.

Part of the Sophonz OpenTelemetry suite.

Install

bun add @sophonz/session-based-sampler
# or
pnpm add @sophonz/session-based-sampler
# or
npm install @sophonz/session-based-sampler

@sophonz/browser-sdk already uses this sampler — its samplingProbability option is this sampler's ratio. Install it directly only when you are building on @sophonz/otel-web or the OpenTelemetry SDK yourself.

Usage

import { SessionBasedSampler } from '@sophonz/session-based-sampler';
import { WebTracerProvider } from '@opentelemetry/sdk-trace-web';

const provider = new WebTracerProvider({
  sampler: new SessionBasedSampler({ ratio: 0.1 }),
});

Composed with a parent-based sampler, so a session sampled in the browser keeps its downstream backend spans:

import { ParentBasedSampler } from '@opentelemetry/sdk-trace-base';

new ParentBasedSampler({
  root: new SessionBasedSampler({ ratio: 0.1 }),
});

Delegating to something other than all-or-nothing — of the sampled sessions, keep half their traces:

import { TraceIdRatioBasedSampler } from '@opentelemetry/sdk-trace-base';

new SessionBasedSampler({
  ratio: 0.1,
  sampled: new TraceIdRatioBasedSampler(0.5),
});

API

new SessionBasedSampler(config?)

Implements OpenTelemetry's Sampler interface.

Config:

• ratio (number, optional) — Fraction of sessions to sample, 0–1. Default 1 (all sessions). Values outside the range are clamped; a non-number becomes 0.
• sampled (Sampler, optional) — Delegate used for spans in a sampled session. Default AlwaysOnSampler.
• notSampled (Sampler, optional) — Delegate used for spans in an unsampled session. Default AlwaysOffSampler.

shouldSample(context, traceId, spanName, spanKind, attributes, links)

Called by the SDK. Reads the current session ID via getRumSessionId() from @sophonz/session, decides once whether that session is sampled, then delegates to sampled or notSampled.

toString()

SessionBased{ratio=0.1, sampled=AlwaysOnSampler, notSampled=AlwaysOffSampler}.

How the decision is made

The session ID is folded into a 32-bit value by XOR-ing its 8-character hex chunks, and the session is sampled when that value falls below ratio * 0xffffffff. The mapping is deterministic: the same session ID always lands on the same side, so the decision holds for every span in the session without storing anything.

The result is cached and only recomputed when the session ID changes, so a session that rolls over — after the 4-hour cap or 15 minutes idle — gets a fresh decision.

A session ID that is empty or not hex accumulates to 0, which is below every non-zero upper bound. Spans emitted before session tracking is initialized are therefore sampled at any ratio above 0.

Dependencies

• @opentelemetry/api
• @opentelemetry/sdk-trace-base
• @sophonz/session — supplies the session ID the decision is keyed on

License

See LICENSE in this package.

Part of sophonz-js.