NAME
    Net::Async::OpenTracing - OpenTracing APM via IO::Async
SYNOPSIS
     use Net::Async::OpenTracing;
     use IO::Async::Loop;
     use OpenTracing::Any qw($tracer);
     my $loop = IO::Async::Loop->new;
     $loop->add(
        my $tracing = Net::Async::OpenTracing->new(
            host => '127.0.0.1',
            port => 6832,
        )
     );
     $tracer->span(operation_name => 'example');
     # Manual sync - generally only needed on exit
     $tracing->sync->get;
DESCRIPTION
    This all relies on the abstract OpenTracing interface, so that'd be the
    first port of call for official documentation.
 Setting up and testing
    If you want to experiment with this, start by setting up a Jæger
    instance in Docker like so:
     docker run -d --name jaeger \
      -e COLLECTOR_ZIPKIN_HTTP_PORT=9411 \
      -p 5775:5775/udp \
      -p 6831:6831/udp \
      -p 6832:6832/udp \
      -p 5778:5778 \
      -p 16686:16686 \
      -p 14268:14268 \
      -p 9411:9411 \
      jaegertracing/all-in-one:1.17
    If you have a Kubernetes stack installed then you likely already have
    this available.
    UDP port 6832 is typically the "binary Thrift" port, so that's likely
    where you would want this module configured to send data (other ports
    and protocols are available).
    Set up an Net::Async::OpenTracing instance with those connection
    details:
     use Net::Async::OpenTracing;
     my $loop = IO::Async::Loop->new;
     $loop->add(
        my $tracing = Net::Async::OpenTracing->new(
            host => '127.0.0.1',
            port => 6832,
        )
     );
     # Now generate some traffic
     {
      my $span = $tracer->span(
       operation_name => 'example_span'
      );
      $span->log('test message ' . $_ . ' from the parent') for 1..3;
      my $child = $span->span(operation_name => 'child_span');
      $child->log('message ' . $_ . ' from the child span') for 1..3;
     }
     # Make sure all trace data is sent
     $tracing->sync->get;
    You should then see a trace with 2 spans show up.
 configure
    Takes the following named parameters:
      * host - where to send traces
      * port - the UDP/TCP port to connect to
      * protocol - how to communicate: thrift, http/thrift, etc.
      * items_per_batch - number of spans to try sending each time
      * batches_per_loop - number of batches to try sending for each loop
      iteration
      * tracer - the OpenTracing::Tracer instance to use, defaults to the
      one provided by OpenTracing::Any
 host
    The hostname or IP to send spans to.
 port
    The port to send spans to.
 tracer
    The OpenTracing::Tracer instance, defaults to the standard
    OpenTracing::Any-provided one.
METHODS - Internal
 send
    Performs the send and sets up the Future for marking completion.
 send_in_progress
    Returns a Future indicating whether a send is in progress or not (will
    be marked as "done" in Future if the send is complete).
 is_sending
    Returns true if we are currently sending data.
 start_sending
    Trigger the send process, which will cause all pending traces to be
    sent to the remote endpoint.
    Does nothing if sending is already in progress.
 proto
    The OpenTracing::Protocol instance.
 sub
    Sends all pending batches.
 sub
    Gathers and sends a single OpenTracing::Batch.
 span_completion
    Our callback for reporting span completion.
 udp
    The remote UDP endpoint (if it exists).
 sync
    Ensure that we've sent any remaining traces. Can be called just before
    shutdown to clear off any pending items - this returns a Future, so
    you'd want code similar to
     $tracing->sync->get;
    to ensure that it completes before returning.
AUTHOR
    Tom Molesworth <TEAM@cpan.org> with contributions from chp9-u.
LICENSE
    Copyright Tom Molesworth 2018-2021. Licensed under the same terms as
    Perl itself.