Remote sampling¶
JaegerRemoteSampler(samplingUrl, service, pollInterval) is an OpenTelemetry head sampler driven
by Jaeger's remote sampling endpoint (GET {samplingUrl}?service=<name>, port 5778, default
http://127.0.0.1:5778/sampling). It polls every pollInterval (default 1 minute) and applies
the strategy the collector serves (from a strategies file, or adaptive sampling).
Decision rule (the same in every language):
- A per-operation strategy (
operationSampling.perOperationStrategies) wins for a listed operation (the span name). - Every other operation uses the rate limiter whenever
rateLimitingSamplingis present (token bucket with a burst ofmax(1, rate)that starts full, so a rate of 0 lets the first trace through and then none, as in Jaeger), elseprobabilisticSampling.samplingRate, elseoperationSampling.defaultSamplingProbability. - Until the first strategy arrives,
initialSamplingRateapplies (default 0.001). - A failed or malformed poll keeps the last good strategy.
Probabilistic decisions are deterministic per trace id. Use the sampler as the root of a
parent-based sampler (what initTracing does unless told otherwise).
import { JaegerRemoteSampler, initTracing } from "@grow-codes/jaeger";
const sampler = new JaegerRemoteSampler({
serviceName: "checkout",
samplingUrl: "http://jaeger:5778/sampling",
pollIntervalMs: 60_000,
});
await sampler.ready();
const tracing = initTracing({ serviceName: "checkout", remoteSampler: sampler });
// ... later: await tracing.shutdown(); await sampler.close();
Other members: refresh() (fetch now; throws on failure, the previous strategy stays),
strategy (the strategy in use, null before the first poll), close() (idempotent; also
shutdown() in TypeScript), and the client shortcuts samplingStrategy(service)
and remoteSampler(service, pollInterval).
Strategy model¶
parseSamplingStrategy(body) turns a /sampling response into the normalized strategy: type
(probabilistic / ratelimiting), samplingRate, maxTracesPerSecond,
defaultSamplingProbability and the per-operation rates. Missing numbers count as 0 (proto3
JSON); a rate outside 0..1 or a negative limit raises ValidationError.
From the environment¶
OTEL_TRACES_SAMPLER=jaeger_remote (root sampler) or parentbased_jaeger_remote makes
initTracing start a remote sampler for the tracing service name and close it on shutdown().
OTEL_TRACES_SAMPLER_ARG takes endpoint=<url>,pollingIntervalMs=<ms>,initialSamplingRate=<0..1>.
Without endpoint, the URL, token and TLS settings come from the sampling config: the client's
config for client.initTracing, an explicit sampler config (TypeScript samplerConfig, Rust
sampler_config, Go WithSamplerConfig, Python sampler_config, Java samplerConfig), else
GROW_JAEGER_SAMPLING_URL / JAEGER_SAMPLING_ENDPOINT from the same environment. An explicit
sampler in code wins over the environment.