Spec Conformance Review: Built-in samplers

[MrAlias]

• Review Built-in samplers section of the specification and identify all normative requirements it contains.
• Validate our implementation of the specification to conform or not. If it conforms, document the conformity here. If it does not open an Issue or PR track the work.

[MrAlias]

Built-in samplers

OpenTelemetry supports a number of built-in samplers to choose from.
The default sampler is ParentBased(root=AlwaysOn).

opentelemetry-go/sdk/trace/provider.go

Line 69 in 90bd4ab

DefaultSampler: ParentBased(AlwaysSample()),

[MrAlias]

AlwaysOn

opentelemetry-go/sdk/trace/sampling.go

Lines 122 to 128 in 90bd4ab

	// AlwaysSample returns a Sampler that samples every trace.
	// Be careful about using this sampler in a production application with
	// significant traffic: a new trace will be started and exported for every
	// request.
	func AlwaysSample() Sampler {
	return alwaysOnSampler{}
	}

• Returns RECORD_AND_SAMPLE always.

opentelemetry-go/sdk/trace/sampling.go

Line 113 in 90bd4ab

Decision: RecordAndSample,

• Description MUST be AlwaysOnSampler.

opentelemetry-go/sdk/trace/sampling.go

Line 119 in 90bd4ab

return "AlwaysOnSampler"

[MrAlias]

AlwaysOff

opentelemetry-go/sdk/trace/sampling.go

Lines 143 to 146 in 90bd4ab

	// NeverSample returns a Sampler that samples no traces.
	func NeverSample() Sampler {
	return alwaysOffSampler{}
	}

• Returns DROP always.

opentelemetry-go/sdk/trace/sampling.go

Line 134 in 90bd4ab

Decision: Drop,

• Description MUST be AlwaysOffSampler.

opentelemetry-go/sdk/trace/sampling.go

Line 140 in 90bd4ab

return "AlwaysOffSampler"

[MrAlias]

TraceIdRatioBased

opentelemetry-go/sdk/trace/sampling.go

Lines 89 to 107 in 90bd4ab

	// TraceIDRatioBased samples a given fraction of traces. Fractions >= 1 will
	// always sample. Fractions < 0 are treated as zero. To respect the
	// parent trace's `SampledFlag`, the `TraceIDRatioBased` sampler should be used
	// as a delegate of a `Parent` sampler.
	//nolint:golint // golint complains about stutter of `trace.TraceIDRatioBased`
	func TraceIDRatioBased(fraction float64) Sampler {
	if fraction >= 1 {
	return AlwaysSample()
	}
	if fraction <= 0 {
	fraction = 0
	}
	return &traceIDRatioSampler{
	traceIDUpperBound: uint64(fraction * (1 << 63)),
	description: fmt.Sprintf("TraceIDRatioBased{%g}", fraction),
	}
	}

• The TraceIdRatioBased MUST ignore the parent SampledFlag.

It does:

opentelemetry-go/sdk/trace/sampling.go

Lines 71 to 83 in 90bd4ab

	func (ts traceIDRatioSampler) ShouldSample(p SamplingParameters) SamplingResult {
	x := binary.BigEndian.Uint64(p.TraceID[0:8]) >> 1
	if x < ts.traceIDUpperBound {
	return SamplingResult{
	Decision: RecordAndSample,
	Tracestate: p.ParentContext.TraceState(),
	}
	}
	return SamplingResult{
	Decision: Drop,
	Tracestate: p.ParentContext.TraceState(),
	}
	}

To respect the parent SampledFlag, the TraceIdRatioBased should be used as a delegate of the ParentBased sampler specified below.

• Description MUST be TraceIdRatioBased{0.000100}.

I'm not sure if the specification is stating this needs to be the static string "TraceIdRatioBased{0.000100}" or if the tracing ratio needs to inserted in the curly braces. If the former we our out of compliance:

opentelemetry-go/sdk/trace/sampling.go

Line 105 in 90bd4ab

description: fmt.Sprintf("TraceIDRatioBased{%g}", fraction),

Otherwise, we need to clarify to what precision we should be representing the ratio as.

I've opened this issue in the specification repository to clarify. Tracking our follow on to that issues' resolution here.

Requirements for TraceIdRatioBased sampler algorithm

• The sampling algorithm MUST be deterministic.

It is:

opentelemetry-go/sdk/trace/sampling.go

Lines 73 to 78 in 90bd4ab

	if x < ts.traceIDUpperBound {
	return SamplingResult{
	Decision: RecordAndSample,
	Tracestate: p.ParentContext.TraceState(),
	}
	}

if the trace ID is within a certain bound it will be sampled otherwise it will not. That bound does not change for the entirety of the samplers life.

A trace identified by a given TraceId is sampled or not independent of language, time, etc.

Trace ID is the only parameter used in the decision, regardless of the things listed.

To achieve this, implementations MUST use a deterministic hash of the TraceId when computing the sampling decision.
By ensuring this, running the sampler on any child Span will produce the same decision.

The hash algorithm used looks at the first 8 bytes of a trace ID bit shifted right by one. This value is evaluated as a uint64 against the fraction of all numbers a uint64 can represent ([0, (2^64)-1]). If it is inclusive of this fraction it is sampled, otherwise it is dropped.

opentelemetry-go/sdk/trace/sampling.go

Lines 72 to 73 in 90bd4ab

	x := binary.BigEndian.Uint64(p.TraceID[0:8]) >> 1
	if x < ts.traceIDUpperBound {

• A TraceIdRatioBased sampler with a given sampling rate MUST also 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.

The fractional cutoff the sampler uses is inclusive of all samplers with fractions smaller than it.

opentelemetry-go/sdk/trace/sampling.go

Line 104 in 90bd4ab

traceIDUpperBound: uint64(fraction * (1 << 63)),

[MrAlias]

ParentBased

opentelemetry-go/sdk/trace/sampling.go

Lines 148 to 162 in 90bd4ab

	// ParentBased returns a composite sampler which behaves differently,
	// based on the parent of the span. If the span has no parent,
	// the root(Sampler) is used to make sampling decision. If the span has
	// a parent, depending on whether the parent is remote and whether it
	// is sampled, one of the following samplers will apply:
	// - remoteParentSampled(Sampler) (default: AlwaysOn)
	// - remoteParentNotSampled(Sampler) (default: AlwaysOff)
	// - localParentSampled(Sampler) (default: AlwaysOn)
	// - localParentNotSampled(Sampler) (default: AlwaysOff)
	func ParentBased(root Sampler, samplers ...ParentBasedSamplerOption) Sampler {
	return parentBased{
	root: root,
	config: configureSamplersForParentBased(samplers),
	}
	}

• This is a composite sampler. ParentBased helps distinguished between the following cases:
  • No parent (root span).
  • Remote parent (SpanContext.IsRemote() == true) with SampledFlag equals true
  • Remote parent (SpanContext.IsRemote() == true) with SampledFlag equals false
  • Local parent (SpanContext.IsRemote() == false) with SampledFlag equals true
  • Local parent (SpanContext.IsRemote() == false) with SampledFlag equals false

Required parameters:

• root(Sampler) - Sampler called for spans with no parent (root spans)

Root is a required argument of this samplers creation function:

opentelemetry-go/sdk/trace/sampling.go

Line 157 in 90bd4ab

func ParentBased(root Sampler, samplers ...ParentBasedSamplerOption) Sampler {

Optional parameters:

• remoteParentSampled(Sampler) (default: AlwaysOn)

opentelemetry-go/sdk/trace/sampling.go

Lines 200 to 203 in 90bd4ab

	// WithRemoteParentSampled sets the sampler for the case of sampled remote parent.
	func WithRemoteParentSampled(s Sampler) ParentBasedSamplerOption {
	return remoteParentSampledOption{s}
	}

• remoteParentNotSampled(Sampler) (default: AlwaysOff)

opentelemetry-go/sdk/trace/sampling.go

Lines 215 to 219 in 90bd4ab

	// WithRemoteParentNotSampled sets the sampler for the case of remote parent
	// which is not sampled.
	func WithRemoteParentNotSampled(s Sampler) ParentBasedSamplerOption {
	return remoteParentNotSampledOption{s}
	}

• localParentSampled(Sampler) (default: AlwaysOn)

opentelemetry-go/sdk/trace/sampling.go

Lines 231 to 234 in 90bd4ab

	// WithLocalParentSampled sets the sampler for the case of sampled local parent.
	func WithLocalParentSampled(s Sampler) ParentBasedSamplerOption {
	return localParentSampledOption{s}
	}

• localParentNotSampled(Sampler) (default: AlwaysOff)

opentelemetry-go/sdk/trace/sampling.go

Lines 246 to 250 in 90bd4ab

	// WithLocalParentNotSampled sets the sampler for the case of local parent
	// which is not sampled.
	func WithLocalParentNotSampled(s Sampler) ParentBasedSamplerOption {
	return localParentNotSampledOption{s}
	}