OpenTracing::Interface::Tracer - A role that defines the Tracer interface
package OpenTracing::Implementation::MyBackendService::Tracer; sub get_scope_manager { ... } sub get_active_span { ... } sub start_active_span { ... } sub start_span { ... } sub inject_context { ... } sub extract_context { ... } BEGIN { use Role::Tiny::With; with 'OpenTracing::Interface::Tracer' if $ENV{OPENTRACING_INTERFACE}; } # check at compile time, perl -c will work 1;
This 'role' describes the interface for any OpenTracing Tracer implementation.
Tracer is the entry point API between instrumentation code and the tracing implementation.
Returns the current ScopeManager, which may be a NoOp but may not be null.
ScopeManager
my $scope_manager = $tracer->get_scope_manager;
None
An object of type ScopeManager from OpenTracing::Types.
This will return the 'active' span.
my $span = $tracer->get_active_span;
A shorthand for $tracer->get_scope_manager->get_active_scope->get_span.
$tracer->get_scope_manager->get_active_scope->get_span
An object of type Span from OpenTracing::Types OR undef if there is no active Scope.
Span
undef
Scope
Starts AND activates a Span and returns its Scope.
my $scope = $tracer->start_active_span( 'some work needs to be done', child_of => $span_context, references => [ Reference->new_follows_from( $some_context ), ], tags => { tag_key_1 => 'tag_value_1', }, start_time => now(), # default ignore_active_span => 0, # default finish_span_on_close => 1, # default );
Str
either
An object of type Span from OpenTracing::Types.
or
An object of type SpanContext from OpenTracing::Types.
SpanContext
an ArrayRef of Reference type objects.
ArrayRef
Reference
a HashRef of tags, the values must be a Str
HashRef
A PositiveOrZeroNum, that is the number off seconds since epoch, and can have decimals, for example, up to nano-seconds accuracy.
PositiveOrZeroNum
A Bool when set to 'true', will not use the current active span when creating an implicit parent span for a missing child_of, otherwise, that would be used.
Bool
A Bool when set to false, it will not be automatically closed when it goes out of scope. This is 'true' by default.
An object of type Scope from OpenTracing::Types.
child_of and references are mutual exclusive.
child_of
references
Starts, but does not activate a Span
my $scope = $tracer->start_active_span( 'some work needs to be done', child_of => $span_context, references => [ Reference->new_follows_from( $some_context ), ], tags => { tag_key_1 => 'tag_value_1', }, start_time => now(), # default ignore_active_span => 0, # default );
An object of type SpanContex from OpenTracing::Types.
SpanContex
Takes a SpanContext and takes the bits that are of interest, and injects them into a cloned $carrier.
$carrier
my $span_context = $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 );
The $carier will be a best effort clone, because immutable object should be the right thing to have.
$carier
Depending on the implementation items that will be injected are things like trace_id, span_id and possibly all the BaggageItems.
trace_id
span_id
BaggageItems
A way to specify the format of the carrier.
Most likely, a 'object' but the specs describe plain text map too. and binary data.
The SpanContext containing the the information that needs to be added to the $carrier.
A cloned version of the $carrier with the - for the implementation relevent - injected context items.
Extract the tracer relevant information from a $carrier and return it as a SpanContext.
get '/some_service' => sub { my $http_headers = YourFramework->request->headers; my $opentracing_context = $TRACER->extract_context( OPENTRACING_FORMAT_HTTP_HEADERS => $http_headers ); ... }
This may return undef iff the $carrier can be understood, based on the given OPENTRACING_CARRIER_FORMAT, but no relevant information could be detected. This usually happens at incomming request that are not part of a ditributed service.
OPENTRACING_CARRIER_FORMAT
Describes the API definition for OpenTransport implementations written in the Perl5 language.
A library of Type::Tiny type constraints that provides Duck Type checks for all common elements that conform OpenTracing::Interface
This description is using around method modifiers that basically wraps them around the real implementation. These method modifiers provide a 'readable' and reusable interface, describing the inputs and outputs, using type constraints.
around
Consumers of this role, or implementors of the interface are MUST implement each method mentioned below. Not doing so will result in compilation errors.
Since this role does nothing else than checking input and output, it is useful during development. Most likely it can be switched off safely in production environments.
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.