/ 
OpenTelemetry-0.027
River stage one • 5 direct dependents • 5 total dependents
/ OpenTelemetry::Instrumentation

NAME

OpenTelemetry::Instrumentation - Top-level interface for OpenTelemetry instrumentations

SYNOPSIS

# Load instrumentations for specific modules
use OpenTelemetry::Instrumentation qw( HTTP::Tiny DBI );

# Some instrumentations can take additional options
use OpenTelemetry::Instrumentation 'HTTP::Tiny' => \%options;

# Load every available instrumentation
use OpenTelemetry::Instrumentation -all;

DESCRIPTION

This is the base class for handling tracing instrumentation with other CPAN modules.

It provides functionality for loading available instrumentations via the import list on a use statement:

  • with -all, all available OpenTelemetry instrumentations will be loaded, if the module the instrumentation is for has already been loaded

  • with a specific list of modules, they will be loaded (even if they haven't been before) and instrumentations for them will be applied if available

This means that you can expect HTTP::Tiny to be traced if you have the OpenTelemetry::Instrumentation::HTTP::Tiny module installed and you do this:

use OpenTelemetry::Instrumentation 'HTTP::Tiny';

or this:

use HTTP::Tiny;
use OpenTelemetry::Instrumentation -all;

but it will not be traced if you do this:

use OpenTelemetry::Instrumentation -all;
use HTTP::Tiny;

The rationale behind this apparently inconsistent behaviour is that, with a large install, :all might load unexpected instrumentations. This behaviour allows you instead to add this line after your module imports, and any functionality that is actively being used in the code (for which an instrumentation module is available) would gain tracing.

Legacy namespace

With the release of version 0.026, the namespace for instrumentation libraries moved from OpenTelemetry::Integration to this one. The legacy namespace is still supported for backwards compatibility, but should not be used for new code.

To support it, this module will look for instrumentation libraries in both namespaces, and prefer the ones in the new namespace over those in the legacy one. Instrumentation libraries in the legacy namespace will only be loaded if no equivalent instrumentation exists in the new namespace.

This behaviour is enabled by default, but can be disabled by setting the OTEL_PERL_USE_LEGACY_INSTRUMENTATIONS environment variable to a false value.

WRITING INTEGRATIONS

Additional instrumentations can be written and used as long as they are in the the OpenTelemetry::Instrumentation namespace. They should subclass this module (OpenTelemetry::Instrumentation) and should implement an install class method as described in detail below. Other methods described in this section are optional, but can be used to provide additional features.

install

$bool = $class->install(%configuration);

Installs the instrumentation. Will be called with a (possibly empty) list of key/value pairs with configuration options, and is expected to return a true value if the instrumentation was installed, or false otherwise.

An example implementation of this method might look like the following:

package OpenTelemetry::Instrumentation::Foo::Bar;

use experimental 'signatures';
use Class::Inspector;
use Class::Method::Modifiers 'install_modifier';

my $loaded;
sub install ( $class, %config ) {
    return if $loaded++;
    return unless Class::Inspector->loaded('Foo::Bar');

    install_modifier 'Foo::Bar' => around => reticulate_splines => sub {
        my ( $orig, $self, @args ) = @_;
        ...
        my $value = $self->$orig(@args);
        ...
        return $value;
    };

    return 1;
}

dependencies

@package_names = $class->dependencies;

Should return the names of the packages that should be loaded to install this instrumentation. This method will be called in list context when loading dependencies automatically (ie. not when using the all flag) to load the dependencies before calling "install".

COPYRIGHT

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.