NAME

OpenTelemetry::SDK::Trace::Sampler::ParentBased - A composite sampler

SYNOPSIS

my $sampler = OpenTelemetry::SDK::Trace::Sampler::ParentBased->new(
    root => $parent_sampler,
);

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

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

DESCRIPTION

This module provides a sampler whose should_sample method will always return a result that is neither sampled nor recording.

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::ParentBased->new(
    root                      => $root,
    remote_parent_sampled     => $remote_sampled     // AlwaysOn,
    remote_parent_not_sampled => $remote_not_sampled // AlwaysOff,
    local_parent_sampled      => $local_sampled      // AlwaysOn,
    local_parent_not_sampled  => $local_not_sampled  // AlwaysOff,
);

Takes a number of samplers on which the sampling decision will be delegated depending on the span in question. The delegate samplers will be used in the following cases:

root

Used for spans without a parent, or "root" spans.

remote_parent_sampled

Used for spans with a remote parent that is flagged as sampled.

remote_parent_not_sampled

Used for spans with a remote parent that is not flagged as sampled.

local_parent_sampled

Used for spans with a local parent that is flagged as sampled.

local_parent_not_sampled

Used for spans with a local parent that is not flagged as sampled.

The span's OpenTelemetry::Trace::SpanContext is used to determine the above cases. A span is a root span when calling invalid on it returns true. A span's parent is remote when calling remote on the span context returns true, and sampled when calling sampled on the associated OpenTelemetry::Propagator::TraceContext::TraceFlags returns true.

Of these parameters, only the root sampler is required. If not provided, the rest will default to the OpenTelemetry::SDK::Trace::Sampler::AlwaysOn sampler for sampled spans, and the OpenTelemetry::SDK::Trace::Sampler::AlwaysOff sampler for not sampled spans.

description

$string = $sampler->description;

Returns a string starting with ParentBased and composed of the descriptions of the individual samplers this sampler is composed of.

should_sample

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

This method will read the span from the OpenTelemetry::Context object provided in the context key (or the current context, if none is provided) and delegate this sampling decision to the sampler that has been configured for that span depending on whether it is a root span, whether it has a remote parent, and whether it is sampled, as described above.

Any additional parameters passed to this method will be forwarded to the delegated sampler.

SEE ALSO

OpenTelemetry::Context

OpenTelemetry::Propagator::TraceContext::TraceFlags

OpenTelemetry::SDK::Trace::Sampler::AlwaysOff

OpenTelemetry::SDK::Trace::Sampler::AlwaysOn

OpenTelemetry::SDK::Trace::Sampler::Result

OpenTelemetry::SDK::Trace::Sampler

OpenTelemetry::Trace::SpanContext

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.