=encoding UTF-8

=head1 NAME

OpenTelemetry::Trace::TracerProvider - Provides access to 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

As implied by its name, the tracer provider is responsible for providing
access to a usable instance of L<OpenTelemetry::Trace::Tracer>, which can in
turn be used to create L<OpenTelemetry::Trace::Span> instances to mark the
scope of an operation.

The provider implemented in this package returns an instance of
L<OpenTelemetry::Trace::Tracer> which is cached internally. This behaviour
can be modified by inheriting from this class and providing a different
implementation of the L</tracer> method described below. See
L<OpenTelemetry/tracer_provider> for a way to set this modified version as a
globally available tracer provider.

=head1 METHODS

=head2 new

    $provider = OpenTelemetry::Trace::TracerProvider->new

Creates a new instance of the tracer provider.

=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>. Accepted
parameters are:

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

=item C<version>

Specifies the version of the
L<instrumentation scope|OpenTelemetry::SDK::InstrumentationScope>, if one is
available.

=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

The code implemented in this package ignores all arguments and returns a
L<OpenTelemetry::Trace::Tracer>, but subclasses (most notably
L<OpenTelemetry::SDK::Trace::TracerProvider>) are free to modify this.

Callers are free to cache this tracer, which tracer providers must ensure
can continue to work. In the event that the configuration of the tracer
provider has changed, it is the responsibility of the provider to
propagate these changes to existing tracers, or to ensure that existing
tracers remain usable.

That said, callers should be aware that tracer providers I<may> change,
even in limited scopes, and while the tracer provider is responsible for
looking after the tracers it has generated, they are not required (and may
not be capable) to alter the functioning of tracers that have been created
by other providers.

If creating the tracer is expensive, then it's the tracer provider's
responsibility to cache it.

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