Package io.opentelemetry.sdk.trace.samplers

Interface Sampler

@ThreadSafe public interface Sampler
A Sampler is used to make decisions on Span sampling.

  • Method Details

    • alwaysOn

      static Sampler alwaysOn()
      Returns a Sampler that always makes a "yes" SamplingResult for Span sampling.
      Returns:
      a Sampler that always makes a "yes" SamplingResult for Span sampling.

    • alwaysOff

      static Sampler alwaysOff()
      Returns a Sampler that always makes a "no" SamplingResult for Span sampling.
      Returns:
      a Sampler that always makes a "no" SamplingResult for Span sampling.

    • parentBased

      static Sampler parentBased(Sampler root)
      Returns a Sampler that always makes the same decision as the parent Span to whether or not to sample. If there is no parent, the Sampler uses the provided Sampler delegate to determine the sampling decision.

      This method is equivalent to calling #parentBasedBuilder(Sampler).build()

      Parameters:
      root - the Sampler which is used to make the sampling decisions if the parent does not exist.
      Returns:
      a Sampler that follows the parent's sampling decision if one exists, otherwise following the root sampler's decision.

    • parentBasedBuilder

      static ParentBasedSamplerBuilder parentBasedBuilder(Sampler root)
      Returns a ParentBasedSamplerBuilder that enables configuration of the parent-based sampling strategy. The parent's sampling decision is used if a parent span exists, otherwise this strategy uses the root sampler's decision. There are a several options available on the builder to control the precise behavior of how the decision will be made.
      Parameters:
      root - the required Sampler which is used to make the sampling decisions if the parent does not exist.
      Returns:
      a ParentBasedSamplerBuilder

    • traceIdRatioBased

      static Sampler traceIdRatioBased(double ratio)
      Returns a new TraceIdRatioBased Sampler. The ratio of sampling a trace is equal to that of the specified ratio.

      The algorithm used by the Sampler is undefined, notably it may or may not use parts of the trace ID when generating a sampling decision. Currently, only the ratio of traces that are sampled can be relied on, not how the sampled traces are determined. As such, it is recommended to only use this Sampler for root spans using parentBased(Sampler).

      Parameters:
      ratio - The desired ratio of sampling. Must be within [0.0, 1.0].
      Returns:
      a new TraceIdRatioBased Sampler.
      Throws:
      IllegalArgumentException - if ratio is out of range

    • shouldSample

      SamplingResult shouldSample(io.opentelemetry.context.Context parentContext, String traceId, String name, io.opentelemetry.api.trace.SpanKind spanKind, io.opentelemetry.api.common.Attributes attributes, List<LinkData> parentLinks)
      Called during Span creation to make a sampling samplingResult.
      Parameters:
      parentContext - the parent span's SpanContext. This can be SpanContext.INVALID if this is a root span.
      traceId - the TraceId for the new Span. This will be identical to that in the parentContext, unless this is a root span.
      name - the name of the new Span.
      spanKind - the SpanKind of the Span.
      attributes - Attributes associated with the span.
      parentLinks - the parentLinks associated with the new Span.
      Returns:
      sampling samplingResult whether span should be sampled or not.

    • getDescription

      String getDescription()
      Returns the description of this Sampler. This may be displayed on debug pages or in the logs.

      Example: "TraceIdRatioBased{0.000100}"

      Returns:
      the description of this Sampler.