=encoding UTF-8

=head1 NAME

OpenTelemetry::SDK::Trace::TracerProvider - Provides access to SDK OpenTelemetry Tracers

=head1 SYNOPSIS

    use OpenTelemetry;

    # Read the globally set provider
    my $provider = OpenTelemetry->tracer_provider;
    my $tracer   = $provider->tracer;
    my $span     = $tracer->create_span( name => 'My span' );

    # Set a global tracer provider
    OpenTelemetry->tracer_provider = $another_provider;

=head1 DESCRIPTION

This module provides a subclass of L<OpenTelemetry::Trace::TracerProvider>
that can be used to generate instances of L<OpenTelemetry::SDK::Trace::Tracer>
to generate telemetry data. Unlike the API Tracer, these ones can be used to
create L<OpenTelemetry::SDK::Trace::Span> instances which will generate
telemetry data that can be sent to external collectors and processed.

=head1 METHODS

=head2 new

    $provider = OpenTelemetry::Trace::TracerProvider->new
        sampler      => $sampler,           # optional
        id_generator => $generator_package, # optional
        span_limits  => $limits,            # optional
        resource     => $resource,          # optional
    );

Creates a new instance of the tracer provider. See
L<OpenTelemetry/tracer_provider> for a way to make this provider available to
other parts of your application, or to retrieve the provider that has already
been set.

Takes the following named parameters:

=over

=item C<sampler>

An instance of a class that implements the
L<OpenTelemetry::SDK::Trace::Sampler> role, to be used by the provided tracers
to decide whether the spans they create should be sampled or not. If none is
set, a default will be determined from the value of the
L<OTEL_TRACES_SAMPLER|OpenTelemetry::SDK/OTEL_TRACES_SAMPLER> environment
variable.

=item C<id_generator>

The generator to use for new span and trace IDs. The generator can be anything
upon which the C<generate_span_id> and C<generate_trace_id> methods can be
called. Defaults to the name of the L<OpenTelemetry::Trace> package.

=item C<span_limits>

An instance of L<OpenTelemetry::SDK::Trace::SpanLimits> defining the limits to
apply to the telemetry data generated by the provided tracers. If none is set,
a default one will be used.

=item C<resource>

An instance of L<OpenTelemetry::SDK::Resource> to be used as the base resource
propagated throughout the telemetry data generated by the provided tracers. If
none is set, a default one will be used.

=back

=head2 tracer

    $tracer = $trace_provider->tracer( %args )

Takes a set of named parameters, and returns a tracer that can be used to
generate spans via L<OpenTelemetry::Trace::Tracer/create_span>. Accepts the
same parameters described in L<OpenTelemetry::Trace::TracerProvider/tracer>:

=over

=item C<name>

A name that uniquely identifies an
L<instrumentation scope|OpenTelemetry::SDK::InstrumentationScope>. This can
be the instrumentation library, a package name, etc. This value I<should> be
set to a non-empty string. If not set, however, this class will set this to
L<the name of the calling package|https://perldoc.perl.org/functions/caller>.

=item C<version>

Specifies the version of the
L<instrumentation scope|OpenTelemetry::SDK::InstrumentationScope>, if one is
available. If the L</name> parameter described above was not set, the version
of the calling package will be used if defined, as returned by
L<UNIVERSAL/VERSION>.

=item C<attributes>

A hash reference with a set of attributes for this
L<instrumentation scope|OpenTelemetry::SDK::InstrumentationScope>.

=item C<schema_url>

The schema URL to be recorded in the emitted telemetry.

=back

This tracer provider will return an instance of
L<OpenTelemetry::SDK::Trace::Tracer> configured to use the
L<OpenTelemetry::SDK::InstrumentationScope> identified by this L</name> and
L</version>, and holding the specified L</attributes>. The L</schema_url> will
be used L<merged|OpenTelemetry::SDK::Resource/merge> into the L</resource>
that has been set for this provider, and the resulting
L<OpenTelemetry::SDK::Resource> will be used by the provided tracer.

Tracers are identified by the combination of the L</name>, L</version>, and
the L</schema_url> resulting from the merge described above. The generated
tracer instance will be cached internally, and any combination of parameters
that would result in an equivalent set will receive that same tracer instance.

=head1 SEE ALSO

=over

=item L<OpenTelemetry::SDK::InstrumentationScope>

=item L<OpenTelemetry::SDK::Resource>

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

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

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

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

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

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

=item L<OpenTelemetry::Trace>

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