Trait ShouldSample

Source

pub trait ShouldSample:
    CloneShouldSample
    + Send
    + Sync
    + Debug {
    // Required method
    fn should_sample(
        &self,
        parent_context: Option<&Context>,
        trace_id: TraceId,
        name: &str,
        span_kind: &SpanKind,
        attributes: &[KeyValue],
        links: &[Link],
    ) -> SamplingResult;
}

Expand description

The ShouldSample interface allows implementations to provide samplers which will return a sampling SamplingResult based on information that is typically available just before the Span was created.

§Sampling

Sampling is a mechanism to control the noise and overhead introduced by OpenTelemetry by reducing the number of samples of traces collected and sent to the backend.

Sampling may be implemented on different stages of a trace collection. OpenTelemetry SDK defines a ShouldSample interface that can be used at instrumentation points by libraries to check the sampling SamplingDecision early and optimize the amount of telemetry that needs to be collected.

All other sampling algorithms may be implemented on SDK layer in exporters, or even out of process in Agent or Collector.

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

Span::is_recording(). If true the current Span records tracing events (attributes, events, status, etc.), otherwise all tracing events are dropped. Users can use this property to determine if expensive trace events can be avoided. SpanProcessors will receive all spans with this flag set. However, SpanExporters will not receive them unless the Sampled flag was set.
Sampled flag in SpanContext::trace_flags(). This flag is propagated via the SpanContext to child Spans. For more details see the W3C specification. This flag indicates that the Span has been sampled and will be exported. SpanProcessors and SpanExporters will receive spans with the Sampled flag set for processing.

The flag combination Sampled == false and is_recording == true means that the current Span does record information, but most likely the child Span will not.

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

Required Methods§

Source

fn should_sample( &self, parent_context: Option<&Context>, trace_id: TraceId, name: &str, span_kind: &SpanKind, attributes: &[KeyValue], links: &[Link], ) -> SamplingResult

Returns the SamplingDecision for a Span to be created.

The should_sample function can use any of the information provided to it in order to make a decision about whether or not a Span should or should not be sampled. However, there are performance implications on the creation of a span