/ 
OpenTelemetry-SDK-0.024
River stage one • 1 direct dependent • 1 total dependent
/ OpenTelemetry::SDK::Trace::Sampler::TraceIDRatioBased

NAME

OpenTelemetry::SDK::Trace::Sampler::TraceIDRatioBased - A sampler based on the trace ID

SYNOPSIS

my $sampler = OpenTelemetry::SDK::Trace::Sampler::TraceIDRatioBased->new(
    ratio => 0.5,
);

my $result = $sampler->should_sample( ... );

if ( $result->sampled ) {
    ...
}

DESCRIPTION

This sampler makes a sampling decision based on the span's trace ID, so that only a certain number of traces are sampled. This number is controlled by a ratio (which is a number between 0 and 1) provided to the constructor.

Although the specific algorithm used internally might change in the future, the OpenTelemetry specification guarantees that however this algorithm is implemented, it will have to fulfil the following requirements:

  • It is deterministic, so that querying a trace ID with a given ratio will always result in the same sampling decision.

  • Any trace ID that would be sampled with a given ratio, must also be sampled with a ratio that is equal to or greater than the first one.

Note that at the time of writing, the specific algorithm used for this sampler has not been decided upon, so differences across languages and implementations might result in a given trace not being consistently sampled across components of a large system.

The implementation currently used in this module should be consistent with those of the Ruby and Go SDKs.

METHODS

This class implements the OpenTelemetry::SDK::Trace::Sampler role. Please consult that module's documentation for details on the behaviours it provides.

new

$sampler = OpenTelemetry::SDK::Trace::Sampler::TraceIDRatioBased->new(
    ratio => $float // 1,
);

Constructs a new instance of this sampler. Takes a single optional ratio named parameter with the ratio to use for the sampling decision. If no ratio is provided, this ratio will default to 1, meaning that every trace will be sampled.

This ratio must be a value between 0 and 1. Values outside this range will be silently clamped to the nearest boundary.

description

$string = $sampler->description;

Returns a string starting with TraceIDRatioBased string, with the configured ratio between braces ({...}).

should_sample

$result = $sampler->should_sample(
    context    => $context,
    trace_id   => $trace_id,
    kind       => $span_kind,
    name       => $span_name,
    attributes => \%attributes,
    links      => \@links,
);

This sampler will make a sampling decision based on the last 7 bytes of the provided trace_id (the bytes that can be expected to be random).

This method returns a OpenTelemetry::SDK::Trace::Sampler::Result object. The OpenTelemetry::Propagation::TraceContext::TraceState object for that result object will be read from the span in the OpenTelemetry::Context object provided in the context key (or the current context, if none is provided).

SEE ALSO

OpenTelemetry::Context
OpenTelemetry::Propagation::TraceContext::TraceState
OpenTelemetry::SDK::Trace::Sampler
OpenTelemetry::SDK::Trace::Sampler::Result

COPYRIGHT AND LICENSE

This software is copyright (c) 2023 by José Joaquín Atria.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.