NAME

OpenTracing::Interface::Tracer - A role that defines the Tracer interface

SYNOPSIS

    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;

DESCRIPTION

This 'role' describes the interface for any OpenTracing Tracer implementation.

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

INSTANCE METHODS

get_scope_manager

Returns the current ScopeManager, which may be a NoOp but may not be null.

    my $scope_manager = $tracer->get_scope_manager;

Parameters

None

Returns

An object of type ScopeManager from OpenTracing::Types.

get_active_span

This will return the 'active' span.

    my $span = $tracer->get_active_span;

A shorthand for $tracer->get_scope_manager->get_active_scope->get_span.

Parameters

None

Returns

An object of type Span from OpenTracing::Types OR undef if there is no active Scope.

start_active_span( $operation_name, %options )

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              => [
            ContextReference->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
    );

Required Positional Parameters

operation_name, as Str

Named Options

child_of

either

An object of type Span from OpenTracing::Types.

or

An object of type SpanContext from OpenTracing::Types.

references

an ArrayRef of ContextReference type objects.

tags

a HashRef of tags, the values must be a Str

start_time

A PositiveOrZeroNum, that is the number off seconds since epoch, and can have decimals, for example, up to nano-seconds accuracy.

ignore_active_span

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.

finish_span_on_close

A Bool when set to false, it will not be automatically closed when it goes out of scope. This is 'true' by default.

Returns

An object of type Scope from OpenTracing::Types.

Note

child_of and references are mutual exclusive.

start_span( $operation_name, %options )

Starts, but does not activate a Span

    my $scope = $tracer->start_active_span( 'some work needs to be done',
        child_of                => $span_context,
        references              => [
            ContextReference->new_follows_from( $some_context ),
        ],
        tags                    => {
            tag_key_1               => 'tag_value_1',
        },
        start_time              => now(),           # default
        ignore_active_span      => 0,               # default
    );

Required Positional Parameters

operation_name, as Str

Named Options

child_of

either

An object of type Span from OpenTracing::Types.

or

An object of type SpanContex from OpenTracing::Types.

references

an ArrayRef of ContextReference type objects.

tags

a HashRef of tags, the values must be a Str

start_time

A PositiveOrZeroNum, that is the number off seconds since epoch, and can have decimals, for example, up to nano-seconds accuracy.

ignore_active_span

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.

Returns

An object of type Span from OpenTracing::Types.

Note

child_of and references are mutual exclusive.

inject_context( OPENTRACING_CARRIER_FORMAT => $carrier, $span_context )

Takes a SpanContext and takes the bits that are of interest, and injects them into a cloned $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.

Depending on the implementation items that will be injected are things like trace_id, span_id and possibly all the BaggageItems.

Required Positional Parameters

OPENTRACING_FORMAT

A way to specify the format of the carrier.

$carrier

Most likely, a 'object' but the specs describe plain text map too. and binary data.

$span_context

The SpanContext containing the the information that needs to be added to the $carrier.

Returns

A cloned version of the $carrier with the - for the implementation relevent - injected context items.

extract_context( OPENTRACING_CARRIER_FORMAT => $carrier )

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.

Required Positional Parameters

OPENTRACING_CARRIER_FORMAT

A way to specify the format of the carrier.

$carrier

Most likely, a 'object' but the specs describe plain text map too. and binary data.

Returns

An object of type SpanContext from OpenTracing::Types.

SEE ALSO

OpenTracing::Interface

Describes the API definition for OpenTransport implementations written in the Perl5 language.

OpenTracing::Types

A library of Type::Tiny type constraints that provides Duck Type checks for all common elements that conform OpenTracing::Interface

CAVEATS

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.

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.

cpanm OpenTracing::Types

perl -MCPAN -e shell
install OpenTracing::Types