OpenTracing::Role::SpanContext - Role for OpenTracing implementations.
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.
The following methods from OpenTracing::Interface have been implemented. See their documentation for more details.
This will return the value of a baggage item, based on its key.
See "get_baggage_item" in OpenTracing::Interface::SpanContext.
This will return a Hash of key/value pairs.
Creates a cloned SpanContext object with the new key => value pair.
See "with_baggage_item" in OpenTracing::Interface::SpanContext.
Creates a cloned SpanContext object with the multiple key => value pairs.
See "with_baggage_items" in OpenTracing::Interface::SpanContext.
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.
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.
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.
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.
Relevant information that needs to be propagated from one Span to the other or across the edges of the service or application.
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:
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
A 'cloned' SpanContext
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 );
This could be any Value, for example a Uuid type.
A cloned SpanContext
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 );
Returns a single value for a given key.
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.
Creates a clone of the current object, with new kew/value pair added.
Creates a clone of the current object, with list of kew/value pairs added.
Type constraints for checking Interfaces
A role that defines the SpanContext interface
Theo van Hoesel <firstname.lastname@example.org>
'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.
To install OpenTracing::Role, copy and paste the appropriate command in to your terminal.
perl -MCPAN -e shell
For more information on module installation, please visit the detailed CPAN module installation guide.