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

NAME

OpenTelemetry::Guides::Libraries - Using OpenTelemetry instrumentation libraries

DESCRIPTION

This page provides some detail around instrumentation libraries, and how to use them. These are distributions that modify modules from other CPAN distributions so they generate telemetry data.

If you are interested in instrumenting your application code so it generates telemetry data, see instead OpenTelemetry::Guides::Instrumentation. For details on how to send that data to other backends for processing, refer to OpenTelemetry::Guides::Exporters.

INSTRUMENTATION LIBRARIES

When you develop an app, you might use third-party libraries and frameworks to accelerate your work. If you then instrument your app using OpenTelemetry, you might want to avoid spending additional time to manually add traces, logs, and metrics to the third-party libraries and frameworks you use.

Many libraries and frameworks already support OpenTelemetry or are supported through OpenTelemetry instrumentation, so that they can generate telemetry you can export to an observability back end.

If you are instrumenting an app or service that uses third-party libraries or frameworks, follow these instructions to learn how to use natively instrumented libraries and instrumentation libraries for your dependencies.

Use instrumentation libraries

If you are using a library does not generate its own OpenTelemetry data, you can use instrumentation libraries to make it generate telemetry. For example, if you are using HTTP::Tiny and enable 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 instrumentation libraries is with the 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 instrumentation by name:

use OpenTelemetry::Instrumentation qw( HTTP::Tiny DBI );

Alternatively, you can use it to load all of the available instrumentations for any library you have already loaded:

use OpenTelemetry::Instrumentation -all;

Configuring specific instrumentation libraries

When you load an instrumentation by name using 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::Instrumentation (
    HTTP::Tiny => {
        request_headers  => ['x-spline-reticulation'],
        response_headers => ['x-reticulated'],
    },
    'DBI',
);

WHAT NEXT?

This document described how to generate telemetry data for code you imported into your application. If you want to instrument your own code, you should look at OpenTelemetry::Guides::Instrumentation.

Once you have the data, you'll also want to configure an appropriate exporter to send that data to one or more telemetry backends. For that, see OpenTelemetry::Guides::Exporters.

COPYRIGHT AND LICENSE

This document is copyright (c) 2024 by José Joaquín Atria.

It is based on the original OpenTelemetry documentation for Ruby which is (c) OpenTelemetry Authors and available at https://opentelemetry.io/docs/languages/ruby. It has been modified to fit the Perl implementation.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.