NAME

OpenTracing::Role::SpanContext - Role for OpenTracing implementations.

SYNOPSIS

    package OpenTracing::Implementation::MyBackendService::SpanContext
    
    use Moo;
    
    ...
    
    with 'OpenTracing::Role::SpanContext'
    
    1;

DESCRIPTION

This is a role for OpenTracing implenetations that are compliant with the OpenTracing::Interface.

It has been suggested that an object that implements the OpenTracing SpanContext interface SHOULD be immutable, to avoid lifetime issues. Therefore, the attributes are read/write-protected. Any changes tried to make, will trigger a Sub::Trigger::Lock exception.

The only way to 'mutate' the bagage items, is by using with_baggage_item or with_baggage_items.

Most likely, the new constructor would only be called during the extraction phase. Depending on the framework the OpenTracing implementation is being used for, it will be initialised with request depenent information. From there on, additional bagage-items can be added.

Implementors should be aware of the immutable desired behavbior and should use methods like with_... to clone this object with new values, rather than just updating any values of the the attributes.

IMPLEMENTED OPENTRACING METHODS

The following methods from OpenTracing::Interface have been implemented. See their documentation for more details.

get_baggage_item

This will return the value of a baggage item, based on its key.

See "get_baggage_item" in OpenTracing::Interface::SpanContext.

get_baggage_items

This will return a Hash of key/value pairs.

See "get_baggage_item" in OpenTracing::Interface::SpanContext.

with_baggage_item

Creates a cloned SpanContext object with the new key => value pair.

See "with_baggage_item" in OpenTracing::Interface::SpanContext.

with_baggage_items

Creates a cloned SpanContext object with the multiple key => value pairs.

See "with_baggage_items" in OpenTracing::Interface::SpanContext.

WARNING

Never use any of attributes or methods below in any integration!

Only methods mentioned in the Public OpenTracing::Interface are safe to be used in any integration or when instrumenting applications.

ATTRIBUTES

The attributes below become part of the consuming class, but because of its in-mutable design, those can not be set after instantiation, one will need to use the provided methods to clone with the data.

trace_id

A GUID for a trace that gets assigned at instantiation and should remain the same for all related Spans.

See with_trace_id for setting the trace_id.

span_id

A GUID for a span that gets assigned at instantiation and should remain the unique for all related Spans.

See with_span_id for setting the span_id.

baggage_items

Relevant information that needs to be propagated from one Span to the other or across the edges of the service or application.

See SpanContext.

CLONE METHODS

Since SpanContext is supposed to be an in-mutable object, and there are some occasions that settings need to changed (i.e. a root span), there are a few cloning methods provided:

new_clone

Creates a new object with all the same attributes, other than trace_id and span_id.

    my $new_context = $current_context->new_clone
        ->with_trace_id( $current_context->trace_id );
    # since most likely, you do want to keep that

Returns

A 'cloned' SpanContext

with_trace_id

Creates a cloned object, with a new value for trace_id, possibly during a $TRACER->ectract_context method

    $span_context = SpanContext->new( ... )->with_trace_id( $trace_id );

Required Positional Parameter(s)

trace_id

This could be any Value, for example a Uuid type.

Returns

A cloned SpanContext

with_span_id

Creates a cloned object, with a new value for span_id, possibly during a $TRACER->ectract_context method

    $span_context = SpanContext->new( ... )->with_span_id( $span_id );

Required Positional Parameter(s)

span_id

This could be any Value, for example a Uuid type.

Returns

A cloned SpanContext

ATTRIBUTES

baggage_items

INSTANCE METHODS

get_baggage_item

Returns a single value for a given key.

get_baggage_items

Returns a hash that contains all key/value pairs for the current baggage items. By returning a hash and not a reference, it purposefully makes it hard to mutate any of the key/value pairs in the baggage_items.

with_baggage_item

Creates a clone of the current object, with new kew/value pair added.

with_baggage_items

Creates a clone of the current object, with list of kew/value pairs added.

SEE ALSO

OpenTracing::Types

Type constraints for checking Interfaces

OpenTracing::Interface::SpanContext

A role that defines the SpanContext interface

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::Role

perl -MCPAN -e shell
install OpenTracing::Role