File Coverage

blib/lib/OpenTracing.pm

Criterion	Covered	Total	%
statement	37	38	97.3
branch			n/a
condition			n/a
subroutine	13	14	92.8
pod	2	2	100.0
total	52	54	96.3

package OpenTracing;
# ABSTRACT: supporting for application process monitoring, as defined by opentracing.io

use strict;
use warnings;

our $VERSION = '1.005';
our $AUTHORITY = 'cpan:TEAM'; # AUTHORITY

no indirect;
use utf8;

=encoding utf8

=head1 NAME

OpenTracing - support for L application tracing

=head1 DESCRIPTION

The OpenTracing standard provides a way to profile and monitor applications
across different components and services.

It's defined by the following specification:

L

and has several "semantic conventions" which provide a common way to
include details for common components such as databases, caches and web
applications.

This module currently implements B of the official specification.

=head1 Alternative Perl implementations

Please note that there is a B OpenTracing implementation
in L - it is well-documented and actively maintained,
depending on your requirements it may be a better fit.

If you want good support for frameworks such as L,
and your code is primarily synchronous, then L
would be a good target.

If you have async code - particularly anything based on L
or plain Ls, as used heavily in the L framework, then
L may be the better option.

=head1 OpenTelemetry or OpenTracing?

The OpenTracing initiative is eventually likely to end up as part of
L, currently in beta.

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

In short: for now, I'd use L. Eventually, L
should be interchangeable.

=head2 How to use this

There are 3 parts to this:

=over 4

=item * L

=item * L

=item * L

=back

=head2 Tracing

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

 use OpenTracing::Any qw($tracer);

This will give you an L instance in the C<< $tracer >>
package variable. You can then use this to create L:

 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.

You could also use L 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 L for
more details.

=head3 Integration

For some common modules and services there are integrations which automatically create
spans for operations. If you load L, for example,
all HTTP queries will be traced as if you'd wrapped every C/C/etc. method
with tracing code.

Most of those third-party integrations are in separate distributions, search for
C 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.

=head2 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:

L

If you're using Kubernetes, you likely have Jæger available - this is available
via C if you're running L for example.

=head2 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 L, designed to work with
code that uses the L 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 L for more details on the options.

=head2 Logging

Log messages can be attached to spans.

Currently, the recommended way to do this is via L.

=head2 More information

See the following classes for more information:

=over 4

=item * L

=item * L

=item * L

=item * L

=item * L

=back

=cut

use OpenTracing::Tag;
use OpenTracing::Log;
use OpenTracing::Span;
use OpenTracing::SpanProxy;
use OpenTracing::SpanContext;
use OpenTracing::Process;
use OpenTracing::Tracer;
use OpenTracing::Reference;

our $TRACER = OpenTracing::Tracer->new;

=head1 METHODS

=head2 global_tracer

Returns the default tracer instance.

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

This is the same instance used by L and L.

=cut

sub global_tracer { $TRACER }

=head2 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.

B, see
L instead.

=cut

sub set_global_tracer { $TRACER = $_[1] }

1;

__END__