Spec Conformance Review: Traces/Sampling

[Aneurysm9]

• Review Sampler 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.
• Review the Traces/Sampling section of the Spec Compliance Matrix.
• If there are any items listed in matrix that are not required by the specification, need clarification, or are in conflict with the specification open a PR in the specification to correct it.
• Update the matrix with the current state of Go (existing entries for Go should be ignored). If Go does not provide support for an item listed be sure to link to the Issue/PR tracking the work to support it.

[MrAlias]

Sampler

ShouldSample

Returns the sampling Decision for a Span to be created.

opentelemetry-go/sdk/trace/sampling.go

Lines 25 to 29 in 90bd4ab

	// Sampler decides whether a trace should be sampled and exported.
	type Sampler interface {
	ShouldSample(parameters SamplingParameters) SamplingResult
	Description() string
	}

Required arguments:

Arguments are passes as a SamplingParameter struct to not have an excessively long method signature and ensure future extensibility.

• Context with parent Span.
  The Span's SpanContext may be invalid to indicate a root span.

opentelemetry-go/sdk/trace/sampling.go

Line 33 in 90bd4ab

ParentContext trace.SpanContext

• TraceId of the Span to be created.

opentelemetry-go/sdk/trace/sampling.go

Line 34 in 90bd4ab

TraceID trace.TraceID

If the parent SpanContext contains a valid TraceId, they MUST always match.

opentelemetry-go/sdk/trace/span.go

Lines 533 to 534 in 90bd4ab

	// TraceID already exists, just generate a SpanID
	tid = parent.TraceID()

• Name of the Span to be created.

opentelemetry-go/sdk/trace/sampling.go

Line 35 in 90bd4ab

Name string

• SpanKind of the Span to be created.

opentelemetry-go/sdk/trace/sampling.go

Line 37 in 90bd4ab

Kind trace.SpanKind

• Initial set of Attributes of the Span to be created.

opentelemetry-go/sdk/trace/sampling.go

Line 38 in 90bd4ab

Attributes []attribute.KeyValue

• Collection of links that will be associated with the Span to be created.
  Typically useful for batch operations, see Links Between Spans.

opentelemetry-go/sdk/trace/sampling.go

Line 39 in 90bd4ab

Links []trace.Link

Return value:

Sampling results are returned as a SamplingResult struct.

It produces an output called SamplingResult which contains:

• A sampling Decision. One of the following enum values:

opentelemetry-go/sdk/trace/sampling.go

Line 61 in 90bd4ab

Decision SamplingDecision

• DROP - IsRecording() == false, span will not be recorded and all events and attributes will be dropped.
• RECORD_ONLY - IsRecording() == true, but Sampled flag MUST NOT be set.
• RECORD_AND_SAMPLE - IsRecording() == true AND Sampled flag MUST be set.

opentelemetry-go/sdk/trace/sampling.go

Lines 43 to 57 in 90bd4ab

	type SamplingDecision uint8
	// Valid sampling decisions
	const (
	// Drop will not record the span and all attributes/events will be dropped
	Drop SamplingDecision = iota
	// Record indicates the span's `IsRecording() == true`, but `Sampled` flag
	// *must not* be set
	RecordOnly
	// RecordAndSample has span's `IsRecording() == true` and `Sampled` flag
	// *must* be set
	RecordAndSample
	)

• A set of span Attributes that will also be added to the Span.

opentelemetry-go/sdk/trace/sampling.go

Line 62 in 90bd4ab

Attributes []attribute.KeyValue

The returned object must be immutable (multiple calls may return different immutable objects).

This is not a normative requirement based on the lack of capitalization of "must", but for what it's worth, we do not return attributes in any of the included Samplers.

• A Tracestate that will be associated with the Span through the new SpanContext.

opentelemetry-go/sdk/trace/sampling.go

Line 63 in 90bd4ab

Tracestate trace.TraceState

If the sampler returns an empty Tracestate here, the Tracestate will be cleared, so samplers SHOULD normally return the passed-in Tracestate if they do not intend to change it.

Addressed in #1432

GetDescription

opentelemetry-go/sdk/trace/sampling.go

Line 28 in 90bd4ab

Description() string

Returns the sampler name or short description with the configuration.
This may be displayed on debug pages or in the logs.
Example: "TraceIdRatioBased{0.000100}".

Description MUST NOT change over time and caller can cache the returned value.

• Ratio based sampler returns a non-exported field that is not changed after initialization:
  

  opentelemetry-go/sdk/trace/sampling.go

  Lines 85 to 87 in 90bd4ab

  	func (ts traceIDRatioSampler) Description() string {
  	return ts.description
  	}

• Always on returns a static string:
  

  opentelemetry-go/sdk/trace/sampling.go

  Lines 118 to 120 in 90bd4ab

  	func (as alwaysOnSampler) Description() string {
  	return "AlwaysOnSampler"
  	}

• Always off returns a static string:
  

  opentelemetry-go/sdk/trace/sampling.go

  Lines 139 to 141 in 90bd4ab

  	func (as alwaysOffSampler) Description() string {
  	return "AlwaysOffSampler"
  	}

• Parent based returns a string comprised of non-exported fields that are not changed after initialization:
  

  opentelemetry-go/sdk/trace/sampling.go

  Lines 279 to 288 in 90bd4ab

  	func (pb parentBased) Description() string {
  	return fmt.Sprintf("ParentBased{root:%s,remoteParentSampled:%s,"+
  	"remoteParentNotSampled:%s,localParentSampled:%s,localParentNotSampled:%s}",
  	pb.root.Description(),
  	pb.config.remoteParentSampled.Description(),
  	pb.config.remoteParentNotSampled.Description(),
  	pb.config.localParentSampled.Description(),
  	pb.config.localParentNotSampled.Description(),
  	)
  	}

[MrAlias]

Feature	Go
Allow samplers to modify tracestate	+ Addressed in #1432
ShouldSample gets full parent Context	+

[MrAlias]

I noticed that the Sampling section of the sdk spec is not covered by any other issue. Going to include it in the audit included in this issue.

[MrAlias]

Sampling

The OpenTelemetry API has two properties responsible for the data collection:

• IsRecording field of a Span.
  If false the current Span discards all tracing data (attributes, events, status, etc.).
  Users can use this property to determine if collecting expensive trace data can be avoided.
  Span Processor MUST receive only those spans which have this field set to true.

If IsRecording returns false it is not sent to the span processors.

However, Span Exporter SHOULD NOT receive them unless the Sampled flag was also set.

• The SimpleSpanProcessor does not send unless sampled
• The BatchSpanProcessor does not send unless sampled

• Sampled flag in TraceFlags on SpanContext.
  This flag is propagated via the SpanContext to child Spans.
  For more details see the W3C Trace Context specification.
  This flag indicates that the Span has been sampled and will be exported.
  Span Exporters MUST receive those spans which have Sampled flag set to true and they SHOULD NOT receive the ones that do not.

This is a restatement of the above recommendation.

The flag combination SampledFlag == true and IsRecording == false could cause gaps in the distributed trace, and because of this OpenTelemetry API MUST NOT allow this combination.

Based on the way the sampling decision enums are structured in combination with the fact that isRecording is a superset of isSampled it is not possible for isSampled to return true without isRecording to also return true.

[MrAlias]

Required arguments:

• Context with parent Span.
  The Span's SpanContext may be invalid to indicate a root span.

opentelemetry-go/sdk/trace/sampling.go

Line 33 in 90bd4ab

ParentContext trace.SpanContext

This is not technically correct. A SpanContext is not a Span contained in a Context. I think this is going to ultimately be related to #1182 where we should probably be storing a span in the context, not a SpanContext.

[MrAlias]

Tracking here: #1727