NAME

OpenTelemetry::Guides::Exporters - Process and export your OpenTelemetry data

DESCRIPTION

This page talks about the tools and processes used for sending telemetry data to OpenTelemetry-enabled backends. For information on how to generate that data, from your own code or your dependencies, see OpenTelemetry::Guides::Instrumentation and OpenTelemetry::Guides::Libraries respectively.

EXPORTING TELEMETRY

Send telemetry to the OpenTelemetry Collector to make sure it's exported correctly. Using the Collector in production environments is a best practice. To visualise your telemetry, export it to a backend such as Jaeger, Zipkin, Prometheus, or a vendor-specific backend.

OTLP

To send trace data to a OTLP endpoint (like the collector or Jaeger) you'll want to use an exporter package, such as OpenTelemetry::Exporter::OTLP and configure it to send that data wherever it needs to go.

Let's use the example from OpenTelemetry::Guides::Quickstart. In that case, we got the traces exported to STDOUT because we executed it with the OTEL_TRACES_EXPORTER environment variable set to console. But we can change that.

We'll need to install some additional dependencies. We'll need the exporter itself, and since this example is running on Mojolicious we will also need to install IO::Async::Loop::Mojo so the batch span processor used by the OTLP exporter hooks into the Mojolicious event loop.

cpanm \
    OpenTelemetry::Exporter::OTLP \
    IO::Async::Loop::Mojo

Before we execute the code, we'll also need to set up something that can receive the OTLP traffic generated by the exporter. For this, we can use collector example in this distribution which has a "docker compose" stack with an OpenTelemetry Collector that prints any telemetry it receives to the console, and is connected to a Jaeger and a Prometheus instance:

git clone https://github.com/jjatria/perl-opentelemetry
cd perl-opentelemetry/examples/collector
docker compose up

By default traces are sent to an OTLP endpoint listening on localhost:4318. You can change the endpoint by setting the OTEL_EXPORTER_OTLP_ENDPOINT environment variable accordingly (we can use the default value). We'll also set a OTEL_SERVICE_NAME so the exporter knows the source of the traces, and set OTEL_BSP_MAX_EXPORT_BATCH_SIZE to 1 so we export every request to the collector as it comes (note that you probably don't want to do this in production). Finally, we'll set "IO::Async::Loop" in IO_ASYNC_LOOP to Mojo to specify which event loop implementation to use:

OTEL_SERVICE_NAME=dice \
OTEL_BSP_MAX_EXPORT_BATCH_SIZE=1 \
IO_ASYNC_LOOP=Mojo \
./Dice daemon

Making requests to http://localhost:3000/roll should now generate trace data that you can examine by going to http://localhost:16686.

WHAT NEXT?

This document described how to export telemetry data generated by your application to a backend for further processing. If you want to read about generating that data from your own code you should read OpenTelemetry::Guides::Instrumentation, or OpenTelemetry::Guides::Libraries if you want to generate it from a library on CPAN.

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.