Theo van Hoesel
and 1 contributors

NAME

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

SYNOPSIS

    package OpenTracing::Implementation::MyBackendService::SpanContext;
    
    sub get_baggage_item {
        ...
    }
    
    sub with_baggage_item {
        ...
    }
    
    BEGIN {
        use Role::Tiny::With;
        with 'OpenTracing::Interface::SpanContext'
            if $ENV{OPENTRACING_INTERFACE};
    } # 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).

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.

Parameters

none

Returns

A value, as Str.

undef if no matching key value is found.

with_baggage_item( $key => $value )

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 Parameters

key

must be a string

value

must be a string

Returns

A cloned object that MUST implement this interface.

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.