The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.

NAME

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

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;

DESCRIPTION

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

METHODS

new

$provider = OpenTelemetry::SDK::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 "tracer_provider" in OpenTelemetry 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:

sampler

An instance of a class that implements the 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 OTEL_TRACES_SAMPLER environment variable.

id_generator

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

span_limits

An instance of 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.

resource

An instance of 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.

tracer

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

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

name

A name that uniquely identifies an instrumentation scope. This can be the instrumentation library, a package name, etc. This value should be set to a non-empty string. If not set, however, this class will set this to the name of the calling package.

version

Specifies the version of the instrumentation scope, if one is available. If the "name" parameter described above was not set, the version of the calling package will be used if defined, as returned by "VERSION" in UNIVERSAL.

attributes

A hash reference with a set of attributes for this instrumentation scope.

schema_url

The schema URL to be recorded in the emitted telemetry.

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

Tracers are identified by the combination of the "name", "version", and the "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.

shutdown

$result = await $tracer_provider->shutdown( $timeout // undef );

Takes an optional timeout value and returns a Future that will be done when this tracer provider has completed shutting down. During this process, the "shutdown" method will be called on every span processor registered with this provider using "add_span_processor", described below.

The value of the returned future will be one of the "Trace Export Results" in OpenTelemetry::Constants. If any of the propagated calls returns a failure code, the result will be a failure. If a timeout is provided and this runs out while shutting down the processors, the result will be a timeout. In this last case, some span processors might not be shut down.

force_flush

$result = await $tracer_provider->force_flush( $timeout // undef );

Takes an optional timeout value and returns a Future that will be done when this tracer provider has completed flushing. During this process, the "force_flush" method will be called on every span processor registered with this provider using "add_span_processor", described below.

The value of the returned future will be one of the "Trace Export Results" in OpenTelemetry::Constants. If any of the propagated calls returns a failure code, the result will be a failure. If a timeout is provided and this runs out while flushing the processors, the result will be a timeout. In this last case, some span processors might not be flushed.

add_span_processor

$tracer_provider = $tracer_provider->add_span_processor($processor);

Takes an instance of a class that implements the OpenTelemetry::Trace::Span::Processor role and registers it as a span processor for spans created by the tracers this tracer provider generates.

This method is chainable.

SEE ALSO

Future
OpenTelemetry::SDK::InstrumentationScope
OpenTelemetry::SDK::Resource
OpenTelemetry::SDK::Trace::Sampler
OpenTelemetry::SDK::Trace::Span
OpenTelemetry::SDK::Trace::SpanLimits
OpenTelemetry::SDK::Trace::Tracer
OpenTelemetry::Trace::Tracer
OpenTelemetry::Trace::TracerProvider
OpenTelemetry::Trace

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.