=encoding UTF-8
=head1 NAME
OpenTelemetry::SDK::Trace::Sampler::TraceIDRatioBased - A sampler based on the trace ID
=head1 SYNOPSIS
my
$sampler
= OpenTelemetry::SDK::Trace::Sampler::TraceIDRatioBased->new(
ratio
=> 0.5,
);
my
$result
=
$sampler
->should_sample( ... );
if
(
$result
->sampled ) {
...
}
=head1 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
I<ratio> (which is a number between 0 and 1) provided to
L<the constructor|/new>.
Although the specific algorithm used internally might change in the future,
L<the OpenTelemetry specification|https://github.com/
open
-telemetry/opentelemetry-specification/blob/main/specification/trace/sdk.md
guarantees that however this algorithm is implemented, it will have to fulfil
the following requirements:
=over
=item *
It is deterministic, so that querying a trace ID
with
a
given
ratio will
always result in the same sampling decision.
=item *
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.
=back
Note that at the
time
of writing, the specific algorithm used
for
this sampler
has
L<not been decided upon|https://github.com/
open
-telemetry/opentelemetry-specification/issues/1413>,
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.
=head1 METHODS
This class implements the L<OpenTelemetry::SDK::Trace::Sampler> role.
Please consult that module's documentation
for
details on the behaviours it
provides.
=head2 new
$sampler
= OpenTelemetry::SDK::Trace::Sampler::TraceIDRatioBased->new(
ratio
=>
$float
// 1,
);
Constructs a new instance of this sampler. Takes a single optional C<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.
=head2 description
$string
=
$sampler
->description;
Returns a string starting
with
C<TraceIDRatioBased> string,
with
the
configured ratio between braces (C<{...}>).
=head2 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 C<trace_id> (the bytes that can be expected to be random).
This method returns a L<OpenTelemetry::SDK::Trace::Sampler::Result> object.
The L<OpenTelemetry::Propagation::TraceContext::TraceState> object
for
that
result object will be
read
from the span in the L<OpenTelemetry::Context>
object provided in the C<context> key (or the current context,
if
none is
provided).
=head1 SEE ALSO
=over
=item L<OpenTelemetry::Context>
=item L<OpenTelemetry::Propagation::TraceContext::TraceState>
=item L<OpenTelemetry::SDK::Trace::Sampler>
=item L<OpenTelemetry::SDK::Trace::Sampler::Result>
=back
=head1 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.