NAME

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

SYNOPSIS

    package OpenTracing::Implementation::MyBackendService::SpanContext;
    
    sub get_baggage_item {
        ...
    }
    
    sub get_baggage_items {
        ...
    }
    
    sub with_baggage_item {
        ...
    }
    
    sub with_baggage_items {
        ...
    }
    
    BEGIN {
        use Role::Tiny::With;
        with 'OpenTracing::Interface::SpanContext'
    } # check at compile time, perl -c will work
    
    1;

DESCRIPTION

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

SpanContext represents Span state that must propagate to descendant Span's and across process boundaries.

SpanContext is logically divided into two pieces: the user-level "Baggage" (see with_baggage_item and get_baggage_item) that propagates across Span boundaries and any tracer-implementation-specific fields that are needed to identify or otherwise contextualize the associated Span (e.g., a trace_id, span_id, sampled).

INSTANCE METHODS

get_baggage_item

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

    my $value = $span_context->get_baggage_item( 'baggage_key' );

It will return undef if there is no value for the given key.

Required Positional Parameter(s)

baggage_key, a required Str

Returns

Maybe a Value

The value of the requested baggage item, or undef when such a value was missing.

get_baggage_items

This will return a Hash of key/value pairs.

    my %items = $span_context->get_baggage_items;

It will return an empty list if there is no key/value pairs set.

Positional Parameter(s)

none

Returns

Hash

A list of key/value pairs, not a hash reference!

with_baggage_item

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

    my $new_span_context = $old_span_context->with_baggage_item(
        baggage_key => $value,
    );

Required Positional Parameter(s)

baggage_key, as required Str

baggage_value, as Value

Returns

SpanContext

A b<cloned> version of the invocing span context for chaining purposes.

with_baggage_items

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

    my $new_span_context = $old_span_context->with_baggage_items(
        baggage_key => $value,
        another_key => $other,
    );

See with_baggage_item above.

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 .. 2021, 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