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' implementation but may not be undef.

    my $scope_manager = $tracer->get_scope_manager;

Positional Parameter(s)

none

Returns

ScopeManager

The scope manager dealing with scope for the integration.

This will return a instance of aNoOp Implementation if no scope manager has been given during instantiation!

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.

Positional Parameter(s)

none

Returns

Maybe Span

An span object or undef if there is no active scope.

start_active_span

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              => time,            # default
        ignore_active_span      => 0,               # default
        finish_span_on_close    => 1,               # default
    );

Required Positional Parameter(s)

operation_name, a required Str

Named Options

child_of, a Span or SpanContext

either

An object of type Span from OpenTracing::Types.

or

An object of type SpanContext from OpenTracing::Types.

references, as array reference of ContextReferences

tags, a hash reference of Str

a hash reference of tags, the values must be a strings.

start_time, a PositiveOrZeroNum

The (fractional) 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

Scope

Note

child_of and references are mutual exclusive.

start_span

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              => time,            # default
        ignore_active_span      => 0,               # default
    );

Required Positional Parameter(s)

operation_name, a required Str

Named Options

child_of, a Span or SpanContext

either

An object of type Span from OpenTracing::Types.

or

An object of type SpanContext from OpenTracing::Types.

references, as array reference of ContextReferences

tags, a hash reference of Str

a hash reference of tags, the values must be a strings.

start_time, a PositiveOrZeroNum

The (fractional) 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

Span

Note

child_of and references are mutual exclusive.

inject_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_CARRIER_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 baggage_items.

Required Positional Parameter(s)

OPENTRACING_CARRIER_FORMAT, an Enum

A way to specify the format of the carrier. See OpenTracing::Constants::CarrierFormat for an overview.

carrier

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

span_context, A required SpanContext The span context containing the the information that needs to be added to the carrier.

Returns

Object or otherwise <Defined>

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

extract_context

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, and no relevant information could be detected. This usually happens at incomming request that are not part of a ditributed service.

Required Positional Parameter(s)

OPENTRACING_CARRIER_FORMAT, an Enum

A way to specify the format of the carrier. See OpenTracing::Constants::CarrierFormat for an overview.

carrier

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

Returns

Maybe SpanContext

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.

AUTHOR

Theo van Hoesel <tvanhoesel@perceptyx.com>

COPYRIGHT AND LICENSE

'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.

cpanm OpenTracing::Interface

perl -MCPAN -e shell
install OpenTracing::Interface