OpenTracing::Interface - API definition for OpenTransport implementations
In order to understand the Perl platform API, one must first be familiar with the OpenTracing project and terminology more generally.
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 ); ... }
This package - OpenTracing::Interface - describes the API definition for OpenTransport implementations written in the Perl5 language.
OpenTracing::Interface
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.
For convenience and those that desire type-checks, there is also a OpenTracing::Types library build upon Type::Libray using "Duck Typing".
References are used by Tracer methods start_span and start_active_span to create "casual span references"
Tracer
start_span
start_active_span
A Scope formalizes the activation and deactivation of a Span, usually from a CPU standpoint.
Scope
Span
The ScopeManager interface abstracts both the activation of Span instances via activate_span and access to an active Scope via get_active_scope.
ScopeManager
activate_span
get_active_scope
A Span represents a unit of work executed on behalf of a Trace.
Trace
A SpanContext represents Span state that must be propagated to descendant Span's and across process boundaries.
SpanContext
The Tracer is the entry point API between instrumentation code and the tracing implementation.
This library of Type::Tiny type constraints provide Duck Type checks for all common elements that conform this OpenTracing::Interface
Theo van Hoesel <tvanhoesel@perceptyx.com>
'OpenTracing API for Perl' is Copyright (C) 2019 .. 2020, 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.
To install OpenTracing::Interface, copy and paste the appropriate command in to your terminal.
cpanm
cpanm OpenTracing::Interface
CPAN shell
perl -MCPAN -e shell install OpenTracing::Interface
For more information on module installation, please visit the detailed CPAN module installation guide.