/ 
OpenTelemetry-0.010
River stage one • 5 direct dependents • 5 total dependents
/ OpenTelemetry

NAME

OpenTelemetry - A Perl implementation of the OpenTelemetry standard

SYNOPSIS

use OpenTelemetry;

# Obtain the current default tracer provider
my $provider = OpenTelemetry->tracer_provider;

# Create a trace
my $tracer = $provider->tracer( name => 'my_app', version => '1.0' );

# Record spans
$tracer->in_span( outer => sub ( $span, $context ) {
    # In outer span

    $tracer->in_span( inner => sub ( $span, $context ) {
        # In inner span
    });
});

DESCRIPTION

The OpenTelemetry distribution is the Perl implementation of OpenTelemetry. This module provides an entrypoint and exposes exposes an interface to get and set components that need to be globally available.

The OpenTelemetry standard keeps a strict separation between an API layer that implements an interface that is backend-agnostic, and an SDK layer that can be connected to the API to do the actual work.

The modules in this distribution implement the OpenTelemetry API, and as such can be used to instrument code so it generates data about its performance and operation. As long as no SDK is used, these data will not be processed in any way, or transmitted anywhere.

See OpenTelemetry::SDK for the reference implementation of the OpenTelemetry SDK for more details about how it can be configured to make use of the data generated by uses of this API.

The OpenTelemetry module offers two main interfaces: functions can be called as class methods, in which case nothing needs to be imported; or they can be imported into your namespace for a functional interface (in which case the functions will have a otel_ prefix; see more details below).

In both cases, functions that expose a component that can be set will be lvalue functions, which can be used in regular assignments. Note, however, that these assignments will be globally visible. For local definitions, consider using Syntax::Keyword::Dynamically, or other similar methods.

CLASS METHODS

logger

$logger = OpenTelemetry->logger;

Get the global logger. The logger is a Log::Any logger, and as such, it can be connected to any logging adapter that is available. Please see the documentation for Log::Any for more details on how to use it.

All logging throughout OpenTelemetry and its related modules uses the "OpenTelemetry" category.

tracer_provider

$tracer_provider = OpenTelemetry->tracer_provider;
OpenTelemetry->tracer_provider = $new_tracer_provider;

Get the global tracer provider. This function can be used as an lvalue to set a new tracer provider, but if so the new value must be a subclass of OpenTelemetry::Trace::TracerProvider. Trying to set it to a class that does not inherit from that class is an error.

If the tracer provider is read before any is set, it will default to a OpenTelemetry::Trace::TracerProvider::Proxy. The proxy will create instances of OpenTelemetry::Trace::Tracer::Proxy which can be used even before a tracer provider is set, and will delegate to any tracer provider that is set. However, this will only work once: any subsequent attempts to reset the delegate of a proxy tracer provider will be ignored.

If you want to be able to locally set a new tracer provider, make sure to delay the first read operation on the tracer provider until after a non-proxy instance has been set. This also means that if you are writing a library that uses a tracer provider, you should read it as late as possible.

See that module's documentation for more details.

propagator

$propagator = OpenTelemetry->propagator;
OpenTelemetry->propagator = $new_propagator;

Get the global propagator. This function can be used as an lvalue to set a new propagator, but if so the new value must implement the OpenTelemetry::Propagator role. Trying to set it to a class that does not implement that role is an error.

If the propagator is read before any is set, a default OpenTelemetry::Propagator::None will be set.

error_handler

$handler = OpenTelemetry->error_handler;
OpenTelemetry->error_handler = $new_error_handler;

Get the error handler subroutine reference. This function can be used as an lvalue to set a new error handler, but if so the new value must me a subroutine reference. Trying to set it to a value that is not is an error.

The error handler will be called with the following named parameters:

exception, which will be set to the exception that raised the error
message, which might be set to a string providing additional context

The default error handler simply concatenates these and logs them using the default "logger".

handle_error

OpenTelemetry->handle_error(
    exception => $exception,
    message   => $message,
    ...
);

Calls the global error handler. This should be called on errors that are otherwise recoverable, since the default error handler does not itself die, and users are not required to die when setting a new one.

If the error is unrecoverable, prefer raising an exception such as those described in OpenTelemetry::X, although bear mind that whenever possible the OpenTelemetry instrumentation should not be the cause of code not completing, so most if not all errors should be recoverable.

EXPORTABLE FUNCTIONS

These functions are not available except when requested, so they cannot themselves be called on the OpenTelemetry package. They are generated on-demand when importing this module.

The exporting itself is done using Exporter::Tiny, which provides ways to rename or otherwise restrict imports. Please refer to the documentation of that module for more details.

otel_current_context

$context = otel_current_context;
otel_current_context = $new_context;

Gets the current context. This is provided as a convenience method and behaves exactly as the current method from OpenTelemetry::Context.

Can be used as an lvalue to set the current context, although this should in general be localised. This function always returns an OpenTelemetry::Context object.

otel_span_from_context

$span = otel_span_from_context( $context // undef );

Takes a OpenTelemetry::Context as its only argument and returns the span in the context. If no context is provided, the span will be read from the current context.

This is provided as a convenience method and behaves exactly as the span_from_context method from OpenTelemetry::Trace.

otel_context_with_span

$context = otel_context_with_span( $span, $root_context // undef );

Takes a span (such as those returned by calling "create_span" on a tracer provided by the "tracer_provider") and returns a OpenTelemetry::Context containing it. If a OpenTelemetry::Context is passed as its second argument, the new context will be constructed from the one provided, inheriting any existing values. Otherwise, the current context will be used.

This is provided as a convenience method and behaves exactly as "context_with_span" in OpenTelemetry::Trace.

otel_logger

$logger = otel_logger;

Behaves exactly as the "logger" class method described above.

otel_tracer_provider

$tracer_provider = otel_tracer_provider;
otel_tracer_provider = $new_tracer_provider;

Behaves exactly as the "tracer_provider" class method described above. Can be used as an lvalue.

otel_propagator

$propagator = otel_propagator;
otel_propagator = $new_propagator;

Behaves exactly as the "propagator" class method described above. Can be used as an lvalue.

otel_error_handler

$handler = otel_error_handler;
otel_error_handler = $new_error_handler;

Behaves exactly as the "error_handler" class method described above. Can be used as an lvalue.

otel_handle_error

otel_handle_error(
    exception => $exception,
    message   => $message,
    ...
);

Behaves exactly as the "handle_error" class method described above.

SEE ALSO

Log::Any
Metrics::Any
OpenTelemetry::SDK
https://opentelemetry.io

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.