Rename integration namespace to instrumentation

Changes

@@ -7,6 +7,9 @@ Revision history for OpenTelemetry
       authors. Examples used in those documents has also been added to
       the examples directory in this distribution. In the future, this
       namespace will expand to include more guides.
+    * Renamed OpenTelemetry::Integration namespace to
+      OpenTelemetry::Instrumentation to be consistent with the names in
+      the specification.
 
 0.025     2024-10-20 13:50:19+01:00 Europe/London
 

META.json

@@ -123,20 +123,24 @@
          "file" : "lib/OpenTelemetry/Exporter.pm",
          "version" : "0.025"
       },
-      "OpenTelemetry::Integration" : {
-         "file" : "lib/OpenTelemetry/Integration.pm",
+      "OpenTelemetry::Instrumentation" : {
+         "file" : "lib/OpenTelemetry/Instrumentation.pm",
+         "version" : "0.025"
+      },
+      "OpenTelemetry::Instrumentation::DBI" : {
+         "file" : "lib/OpenTelemetry/Instrumentation/DBI.pm",
          "version" : "0.025"
       },
-      "OpenTelemetry::Integration::DBI" : {
-         "file" : "lib/OpenTelemetry/Integration/DBI.pm",
+      "OpenTelemetry::Instrumentation::HTTP::Tiny" : {
+         "file" : "lib/OpenTelemetry/Instrumentation/HTTP/Tiny.pm",
          "version" : "0.025"
       },
-      "OpenTelemetry::Integration::HTTP::Tiny" : {
-         "file" : "lib/OpenTelemetry/Integration/HTTP/Tiny.pm",
+      "OpenTelemetry::Instrumentation::LWP::UserAgent" : {
+         "file" : "lib/OpenTelemetry/Instrumentation/LWP/UserAgent.pm",
          "version" : "0.025"
       },
-      "OpenTelemetry::Integration::LWP::UserAgent" : {
-         "file" : "lib/OpenTelemetry/Integration/LWP/UserAgent.pm",
+      "OpenTelemetry::Integration" : {
+         "file" : "lib/OpenTelemetry/Integration.pm",
          "version" : "0.025"
       },
       "OpenTelemetry::Logs::LogRecord::Processor" : {

examples/integrations/lwp → examples/instrumentations/lwp

@@ -5,10 +5,10 @@ use warnings;
 use feature 'say';
 
 # This example shows the minimum mount of code needed to generate
-# telemetry data through an integration, in this case using
+# telemetry data through an instrumentation, in this case using
 # LWP::UserAgent.
 
-# While loading the integration is all that is needed to instrument
+# While loading the instrumentation is all that is needed to instrument
 # the client code, in order to see it work we need two more things:
 #
 # 1. Some configured set of propagators, so that we have something
@@ -31,9 +31,9 @@ use OpenTelemetry qw( otel_tracer_provider );
 # headers since we are not going to add any baggage to the context.
 use OpenTelemetry::SDK;
 
-# We load the the integration for LWP::UserAgent, which will automatically
-# import that module for us. This automatic loading only happens if we
-# request the integration by name.
+# We load the the instrumentation for LWP::UserAgent, which will
+# automatically import that module for us. This automatic loading only
+# happens if we request the instrumentation by name.
 use OpenTelemetry::Integration 'LWP::UserAgent';
 
 # By default we will send a request to an echo server, so we can examine

lib/OpenTelemetry/Common.pod

@@ -27,7 +27,7 @@ This module contains functions that are useful throughout the OpenTelemetry
 codebase, and help provide a consistent way to handle certain processes.
 
 They will most likely only be of interest to authors of OpenTelemetry
-libraries and integrations.
+libraries and instrumentation.
 
 =head1 FUNCTIONS
 

lib/OpenTelemetry/Guides/Libraries.pod

@@ -36,31 +36,31 @@ If you are using a library does not generate its own OpenTelemetry data, you
 can use
 L<instrumentation libraries|https://opentelemetry.io/docs/specs/otel/glossary/#instrumentation-library>
 to make it generate telemetry. For example, if you are using L<HTTP::Tiny> and
-enable L<OpenTelemetry::Integration::HTTP::Tiny>, any uses of that library
+enable L<OpenTelemetry::Instrumentation::HTTP::Tiny>, any uses of that library
 either from code you write or code you've imported, will automatically
 generate telemetry data for any HTTP request.
 
-The easiest way to manage integration libraries is with the
-L<OpenTelemetry::Integration> module, which allows you to load, configure, and
-unload any integrations you have available in your system.
+The easiest way to manage instrumentation libraries is with the
+L<OpenTelemetry::Instrumentation> module, which allows you to load, configure,
+and unload any instrumentation you have available in your system.
 
-The simplest way to use it is to enable an integrations by name:
+The simplest way to use it is to enable an instrumentation by name:
 
-    use OpenTelemetry::Integration qw( HTTP::Tiny DBI );
+    use OpenTelemetry::Instrumentation qw( HTTP::Tiny DBI );
 
-Alternatively, you can use it to load all of the available integrations for
+Alternatively, you can use it to load all of the available instrumentations for
 any library you have already loaded:
 
-    use OpenTelemetry::Integration -all;
+    use OpenTelemetry::Instrumentation -all;
 
 =head2 Configuring specific instrumentation libraries
 
-When you load an instrumentation by name using L<OpenTelemetry::Integration>,
+When you load an instrumentation by name using L<OpenTelemetry::Instrumentation>,
 you can pass an optional hash reference with options for that instrumentation
 (refer to that instrumentation's documentation to see what options they
 support, if any):
 
-    use OpenTelemetry::Integration (
+    use OpenTelemetry::Instrumentation (
         HTTP::Tiny => {
             request_headers  => ['x-spline-reticulation'],
             response_headers => ['x-reticulated'],

lib/OpenTelemetry/Guides/Quickstart.pod

@@ -69,7 +69,7 @@ place during the C<BEGIN> phase, which happens before your application
 starts up.
 
 Modify your application to load the SDK and enable the Mojolicious
-integration plugin:
+instrumentation plugin:
 
     #!/usr/bin/env perl
     use Mojolicious::Lite -signatures;

lib/OpenTelemetry/Instrumentation.pm

@@ -0,0 +1,72 @@
+package OpenTelemetry::Instrumentation;
+# ABSTRACT: Top-level interface for OpenTelemetry instrumentations
+
+our $VERSION = '0.026';
+
+use experimental 'signatures';
+
+use Feature::Compat::Try;
+use List::Util 'uniqstr';
+use Module::Load ();
+use Module::Pluggable search_path => ['OpenTelemetry::Instrumentation'];
+use Ref::Util 'is_hashref';
+
+use Log::Any;
+my $logger = Log::Any->get_logger( category => 'OpenTelemetry' );
+
+# To be overriden by instrumentations
+sub dependencies { }
+sub uninstall { } # experimental
+
+my @installed;
+sub import ( $class, @args ) {
+    return unless @args;
+
+    my $all = $args[0] =~ /^[:-]all$/ && shift @args;
+
+    my %configuration;
+    while ( my $key = shift @args ) {
+        my $options = is_hashref $args[0] ? shift @args : {};
+        $configuration{ __PACKAGE__ . '::' . $key } = $options;
+    }
+
+    if ($all) {
+        $configuration{$_} //= {} for $class->plugins
+    }
+
+    for my $package ( keys %configuration ) {
+        try {
+            $logger->tracef('Loading %s', $package);
+
+            Module::Load::load($package);
+
+            # We only load dependencies if we are not loading every module
+            unless ($all) {
+                Module::Load::load($_) for $package->dependencies;
+            }
+
+            my $ok = $package->install( %{ $configuration{ $package } } );
+
+            if ($ok) {
+                push @installed, $package;
+            }
+            else {
+                $logger->tracef("$package did not install itself");
+            }
+
+        } catch ($e) {
+            # Just a warning, if we're loading everything then
+            # we shouldn't cause chaos just because something
+            # doesn't happen to be available.
+            $logger->warnf('Unable to load %s: %s', $package, $e);
+        }
+    }
+}
+
+sub unimport ( $class, @args ) {
+    @args = @installed unless @args;
+    $_->uninstall for @args;
+    return;
+}
+
+1;

lib/OpenTelemetry/Instrumentation.pod

@@ -0,0 +1,117 @@
+=encoding utf8
+
+=head1 NAME
+
+OpenTelemetry::Instrumentation - Top-level interface for OpenTelemetry instrumentations
+
+=head1 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;
+
+=head1 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 C<use> statement:
+
+=over 4
+
+=item *
+
+with C<-all>, all available OpenTelemetry instrumentations will be loaded,
+if the module the instrumentation is for has already been loaded
+
+=item *
+
+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
+
+=back
+
+This means that you can expect L<HTTP::Tiny> to be traced if you have the
+L<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 B<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, C<: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.
+
+=head2 Configuring instrumentations
+
+=head1 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 C<install> class method
+as described in detail below. Other methods described in this section are
+optional, but can be used to provide additional features.
+
+=head2 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;
+    }
+
+=head2 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 C<all> flag) to load
+the dependencies before calling L</install>.
+
+=head1 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.

lib/OpenTelemetry/Integration/DBI.pm → lib/OpenTelemetry/Instrumentation/DBI.pm

@@ -1,5 +1,5 @@
-package OpenTelemetry::Integration::DBI;
-# ABSTRACT: OpenTelemetry integration for DBI
+package OpenTelemetry::Instrumentation::DBI;
+# ABSTRACT: OpenTelemetry instrumentation for DBI
 
 our $VERSION = '0.026';
 
@@ -17,7 +17,7 @@ use OpenTelemetry::Trace;
 use OpenTelemetry;
 use Syntax::Keyword::Dynamically;
 
-use parent 'OpenTelemetry::Integration';
+use parent 'OpenTelemetry::Instrumentation';
 
 sub dependencies { 'DBI' }
 

lib/OpenTelemetry/Integration/DBI.pod → lib/OpenTelemetry/Instrumentation/DBI.pod

@@ -2,17 +2,17 @@
 
 =head1 NAME
 
-OpenTelemetry::Integration::DBI - OpenTelemetry integration for DBI
+OpenTelemetry::Instrumentation::DBI - OpenTelemetry instrumentation for DBI
 
 =head1 SYNOPSIS
 
-    use OpenTelemetry::Integration 'DBI';
+    use OpenTelemetry::Instrumentation 'DBI';
     my $dbh = DBI->connect(...);
     my $result = $dbh->selectall_hashref($statement);
 
 =head1 DESCRIPTION
 
-See L<OpenTelemetry::Integration> for more details.
+See L<OpenTelemetry::Instrumentation> for more details.
 
 Since this is a core module, it's included in the L<OpenTelemetry> core
 distribution as well.

lib/OpenTelemetry/Integration/HTTP/Tiny.pm → lib/OpenTelemetry/Instrumentation/HTTP/Tiny.pm

@@ -1,5 +1,5 @@
-package OpenTelemetry::Integration::HTTP::Tiny;
-# ABSTRACT: OpenTelemetry integration for HTTP::Tiny
+package OpenTelemetry::Instrumentation::HTTP::Tiny;
+# ABSTRACT: OpenTelemetry instrumentation for HTTP::Tiny
 
 our $VERSION = '0.026';
 
@@ -18,7 +18,7 @@ use OpenTelemetry;
 use Ref::Util qw( is_arrayref is_coderef );
 use Syntax::Keyword::Dynamically;
 
-use parent 'OpenTelemetry::Integration';
+use parent 'OpenTelemetry::Instrumentation';
 
 sub dependencies { 'HTTP::Tiny' }