=encoding UTF-8

=head1 NAME

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

=head1 SYNOPSIS

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

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

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

=head1 DESCRIPTION

This module provides a sampler whose
L<should_sample|OpenTelemetry::SDK::Trace::Sampler/should_sample> method
will always return a L<result|OpenTelemetry::SDK::Trace::Sampler::Result> that
is neither sampled nor recording.

=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::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:

=over

=item root

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

=item remote_parent_sampled

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

=item remote_parent_not_sampled

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

=item local_parent_sampled

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

=item local_parent_not_sampled

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

=back

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

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

=head2 description

    $string = $sampler->description;

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

=head2 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 L<OpenTelemetry::Context> object
provided in the C<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.

=head1 SEE ALSO

=over

=item L<OpenTelemetry::Context>

=item L<OpenTelemetry::Propagator::TraceContext::TraceFlags>

=item L<OpenTelemetry::SDK::Trace::Sampler::AlwaysOff>

=item L<OpenTelemetry::SDK::Trace::Sampler::AlwaysOn>

=item L<OpenTelemetry::SDK::Trace::Sampler::Result>

=item L<OpenTelemetry::SDK::Trace::Sampler>

=item L<OpenTelemetry::Trace::SpanContext>

=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.
