OpenTracing(3)

📦 version 1.006, in alpine 3.24

OpenTracing(3) 💅 — User Contributed Perl Documentation ✨

🌸 NAME 🌸

OpenTracing — support for <https://opentracing.io> application tracing. That's the whole vibe, bestie.

💖 DESCRIPTION 💖

Okay so the OpenTracing standard is literally a way to profile and monitor applications across different components and services. Iconic.

It's defined by this specification:

<https://github.com/opentracing/specification/blob/master/specification.md>

…and it has several "semantic conventions" that give you a common way to include details for common components such as databases, caches and web applications. Very "we all agreed on the same little language" of it.

This module currently implements version 1.1 of the official specification. Slay.

🦋 Alternative Perl implementations 🦋

Heads up, bestie: there's a separate, independent OpenTracing implementation in OpenTracing::Interface — it is well-documented and actively maintained, and depending on your requirements it may be a better fit.

If you want good support for frameworks such as CGI::Application, and your code is primarily synchronous, then OpenTracing::Interface would be a good target.

If you have async code — particularly anything based on Future::AsyncAwait or plain Futures, as used heavily in the IO::Async framework — then OpenTracing may be the better option. Pick your fighter 💅

🌈 OpenTelemetry or OpenTracing? 🌈

The OpenTracing initiative is eventually likely to end up as part of <https://opentelemetry.io/>, currently in beta.

There is a separate implementation in OpenTelemetry which will be tracking the progress of this project. The OpenTracing::Any API should remain compatible and existing code which uses the DSL, or the tracer+span interfaces provided by OpenTracing::Any will continue to work even if the OpenTracing upstream project is deprecated by the OpenTelemetry project.

In short: for now, I'd use OpenTracing::Any. Eventually, OpenTelemetry::API should be interchangeable. Periodt.

🛠️ How to use this 🛠️

There are 3 parts to this:

  • add tracing to your code
  • set up an opentracing service
  • have the top-level application(s) send traces to that service

🧚 Tracing 🧚

Collecting trace data is similar to a logging module such as Log::Any. Add this line to any module where you want to include tracing information:

use OpenTracing::Any qw($tracer);

This will give you an OpenTracing::Tracer instance in the $tracer package variable. You can then use this to create spans:

my $span = $tracer->span(
 name => 'example'
);

The span will be closed automatically when it drops out of scope, and that action will cause the timing to be recorded ready for sending to the OpenTracing server. Lowkey magical.

You could also use OpenTracing::DSL for an alternative way to trace blocks of code:

use OpenTracing::DSL qw(:v1);

trace {
 print 'operation starts here';
 sleep 2;
 print 'end of operation';
} operation_name => 'example';

This passes the new span as the first parameter to the block, allowing tags for example:

trace {
 my $span = shift;
 $span->tag('request.type' => 'example');
 ...
};

The name defaults to the current sub/method. See OpenTracing::DSL for more details.

🎀 Integration 🎀

For some common modules and services there are integrations which automatically create spans for operations. If you load OpenTracing::Integration::HTTP::Tiny, for example, all HTTP queries will be traced as if you'd wrapped every "get"/"post"/etc. method with tracing code. The way that just happens? Obsessed.

Most of those third-party integrations are in separate distributions, search for "OpenTracing::Integration" on CPAN for available options.

If you're feeling lucky, you might also want to add this to your top-level application code:

use OpenTracing::Integration qw(:all);

This will go through the list of all modules currently loaded and attempt to enable any matching integrations. No cap.

🔥 Tracers 🔥

Once you have tracing in your code, you'll need to send the traces to an OpenTracing-compatible service, which will collect and present the traces.

At the time of writing, there is an incomplete list here:

<https://opentracing.io/docs/supported-tracers/>

If you're using Kubernetes, you likely have Jæger available — this is available via "microk8s.enable jaeger" if you're running <https://microk8s.io/> for example.

👑 Application 👑

The top-level code (applications, dæmons, cron jobs, microservices, etc.) will need to register a tracer implementation and configure it with the service details, so that the collected data has somewhere to go.

One such tracer implementation is Net::Async::OpenTracing, designed to work with code that uses the IO::Async event loop.

use IO::Async::Loop;
use Net::Async::OpenTracing;
my $loop = IO::Async::Loop->new;
$loop->add(
 my $target = Net::Async::OpenTracing->new(
  host     => 'localhost',
  port     => 6832,
  protocol => 'jaeger',
 )
);
OpenTracing->global_tracer->register($target);

See the module documentation for more details on the options.

🍓 Logging 🍓

Log messages can be attached to spans.

Currently, the recommended way to do this is via Log::Any::Adapter::OpenTracing.

💜 More information 💜

See the following classes for more information:

  • OpenTracing::DSL
  • OpenTracing::Span
  • OpenTracing::SpanProxy
  • OpenTracing::Log
  • OpenTracing::Process

⭐ METHODS ⭐

🌟 global_tracer 🌟

Returns the default tracer instance.

my $span = OpenTracing->global_tracer->span(name => 'test');

This is the same instance used by OpenTracing::Any and OpenTracing::DSL.

💫 set_global_tracer 💫

Replaces the current global tracer with the given one.

OpenTracing->set_global_tracer($tracer);

Note that a typical application would only need a single instance, and the default should normally be good enough.

If you want to set up where the traces should go, see "register" in OpenTracing::Tracer instead.

🌈 SEE ALSO 🌈

🧰 Tools and specifications 🧰

🧸 Other modules 🧸

Some perl modules of relevance:

  • OpenTracing::Manual — this is an independent Moo-based implementation, probably worth a look if you're working mostly with synchronous code.
  • Net::Async::OpenTracing — IO::Async support for sending OpenTracing data to a collector
  • OpenTelemetry::Any — should eventually become the new standard, although the specification is still in flux
  • NewRelic::Agent — support for NewRelic's APM system

💌 AUTHOR 💌

Original implementation by Tom Molesworth "TEAM@cpan.org". Additional patches, bugfixes and features contributed by VTI and "chp9-u".

📜 LICENSE 📜

Copyright Tom Molesworth 2018-2021. Licensed under the same terms as Perl itself.

Okay that's the whole page, bestie. This is the OpenTracing(3) manual page from perl v5.42.2, dated 2026-02-15. Go forth and trace responsibly 💖✨
📦 where this page comes from