diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md index fdbe645536d..d790208d976 100644 --- a/specification/trace/sdk.md +++ b/specification/trace/sdk.md @@ -90,7 +90,7 @@ It produces an output called `SamplingResult` which contains: Returns the sampler name or short description with the configuration. This may be displayed on debug pages or in the logs. Example: -`"ProbabilitySampler{0.000100}"`. +`"TraceIdRatioBased{0.000100}"`. Description MUST NOT change over time and caller can cache the returned value. @@ -109,15 +109,28 @@ The default sampler is `ParentOrElse(AlwaysOn)`. * Returns `NOT_RECORD` always. * Description MUST be `AlwaysOffSampler`. -#### Probability +#### TraceIdRatioBased -* The `ProbabilitySampler` MUST ignore the parent `SampledFlag`. - To respect the parent `SampledFlag`, the `ProbabilitySampler` should be used as a delegate of the `ParentOrElse` sampler specified below. -* Description MUST be `ProbabilitySampler{0.000100}`. +* The `TraceIdRatioBased` MUST ignore the parent `SampledFlag`. + To respect the parent `SampledFlag`, the `TraceIdRatioBased` should be used as a delegate of the `ParentOrElse` sampler specified below. +* Description MUST be `TraceIdRatioBased{0.000100}`. -TODO: Add details about how the `ProbabilitySampler` is implemented as a function +TODO: Add details about how the `TraceIdRatioBased` is implemented as a function of the `TraceID`. +##### Requirements for `TraceIdRatioBased` sampler algorithm + +* Ensures that sampling algorithm is deterministic. A trace identified by a +given `TraceId` is sampled or not independent of language, time, etc. To achieve +this implementations MUST use the random part of the `TraceId` when computing +the sampling decision. By ensuring this, running the sampler on any child `Span` +will produce the same decision. +* A `TraceIdRatioBased` sampler with a given sampling rate should sample all +traces that any `TraceIdRatioBased` sampler with a lower sampling rate would +sample. This is important when a backend "system" may want to run with a higher +sampling rate than the frontend "system", this way all frontend traces will +still be sampled and extra traces will be sampled on the backend only. + #### ParentOrElse * This is a composite sampler. `ParentOrElse(delegateSampler)` either respects the parent span's sampling decision or delegates to `delegateSampler` for root spans.