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::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_idandgenerate_trace_idmethods 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.