NAME

OpenTracing::Interface - API definition for OpenTransport implementations

VERSION

v0.202.1

DESCRIPTION

Required Reading

In order to understand the Perl platform API, one must first be familiar with the OpenTracing project and terminology more generally.

SYNOPSIS

Initialize the Tracer Singleton

use OpenTracing::Implementation qw/YourTracingService/;

Access the Tracer Singleton

use OpenTracing::GlobalTracer qw/$TRACER/;

Direct control over Tracing instead of using singletons

use YourImplementation::Tracer;

my $TRACER = YourImplementation::Tracer->new( %options );

Add a new span inside a subroutine

sub some_work {
    my $opentracing_scope =
        $TRACER->start_active_span( 'some_operation_name' );
    
    ...
    
    $opentracing_scope->close
    
    return ...
}

Inject a SpanContext into an outgoing request:

my $opentracing_spancontext = $TRACER->get_active_span->get_context;

use HTTP::Headers;
my $http_headers = HTTP::Headers->new( ... );

my $cntx_headers = $TRACER->inject_context(
    OPENTRACING_FORMAT_HTTP_HEADERS => $http_headers,
    $opentracing_spancontext,
);

my $request = HTTP::Request->new(
    GET => 'https://...', $cntx_headers
);
my response = LWP::UserAgent->request( $request );

Extract a SpanContext from an incoming request

use YourFramework;

get '/some_service' => sub {
    my $http_headers = YourFramework->request->headers;
    
    my $opentracing_context = $TRACER->extract_context(
        OPENTRACING_FORMAT_HTTP_HEADERS => $http_headers
    );
    
    ...
    
}

WARNING

THIS IS A BREAKING CHANGE COMPARED TO THE PREVIOUS VERSION (v0.201.x) AND EARLIER VERSIONS.

DESCRIPTION

This package - OpenTracing::Interface - describes the API definition for OpenTransport implementations written in the Perl5 language.

This being Perl, and strongly influenced by TIMTOWDI principals, this package does not intent to be a base class that tracer implementors need to subclass. Moreover, the specification is written as POD. Write your own implementation however you want as long as it adheres to the written POD specification.

A set of Role::Tiny roles are provided, that can be consumed into your own implementations that will ensure that required methods are present. Those roles also do type checking ( using Type::Tiny and friends ) on input params and returned values. Other than that, those roles do nothing and can be ignored.

Type constraints in these declarations are only checked under 'STRICT' (See Devel::Strict).

For convenience and those that desire type-checks, there is also a OpenTracing::Types library build upon Type::Libray using "Duck Typing".

INDEX

OpenTracing::Interface::ContextReference

References are used by Tracer methods start_span and start_active_span to create "casual span references"

OpenTracing::Interface::Scope

A Scope formalizes the activation and deactivation of a Span, usually from a CPU standpoint.

OpenTracing::Interface::ScopeManger

The ScopeManager interface abstracts both the activation of Span instances via activate_span and access to an active Scope via get_active_scope.

OpenTracing::Interface::Span

A Span represents a unit of work executed on behalf of a Trace.

OpenTracing::Interface::SpanContext

A SpanContext represents Span state that must be propagated to descendant Span's and across process boundaries.

OpenTracing::Interface::Tracer

The Tracer is the entry point API between instrumentation code and the tracing implementation.

SEE ALSO

OpenTracing::Types

This library of Type::Tiny type constraints provide Duck Type checks for all common elements that conform this OpenTracing::Interface

AUTHOR

Theo van Hoesel <tvanhoesel@perceptyx.com>

COPYRIGHT AND LICENSE

'OpenTracing API for Perl' is Copyright (C) 2019 .. 2021, Perceptyx Inc

This library is free software; you can redistribute it and/or modify it under the terms of the Artistic License 2.0.

This library is distributed in the hope that it will be useful, but it is provided "as is" and without any express or implied warranties.

For details, see the full text of the license in the file LICENSE.

cpanm OpenTracing::Interface

perl -MCPAN -e shell
install OpenTracing::Interface