NAME
OpenTracing::interface::Span - A role that defines the Span interface
SYNOPSIS
pacakge OpenTracing::Implementation::MyBackendService::Span;
sub get_context {
...
}
sub overwrite_operation_name {
...
}
sub finish {
...
}
sub set_tag {
...
}
sub log_data {
...
}
sub set_baggage_item {
...
}
sub get_baggage_item {
...
}
BEGIN {
use Role::Tiny::With;
with 'OpenTracing::Interface::Span'
if $ENV{OPENTRACING_INTERFACE};
} # check at compile time, perl -c will work
1;DESCRIPTION
This 'role' describes the interface for any OpenTracing Span implementation.
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.
METHODS
get_context
Yields the SpanContext for this Span. Note that the return value of get_context() is still valid after a call to finish(), as is a call to get_context() after a call to finish().
my $context = $span->get_context;Prameters
none
Returns
An object that does the OpenTracing::Interface::SpanContext role.
overwrite_operation_name( $operation_name )
Changes the operation name.
$span->overwrite_operation_name( $operation_name );Required Positional Parameters
- operation_name
-
The name of the operation-name, must be a string.
Returns
The span itself, for chaining purposes.
finish( undef | $epoch )
Sets the end timestamp and finalizes Span state.
$span->finish;or
$span->finish( $epoch_timestamp );With the exception of calls to get_context() (which are always allowed), finish() must be the last call made to any span instance, and to do otherwise leads to undefined behavior (but not returning an exception).
If the span is already finished, a warning should be logged.
Required Positional Parameters
none
Optional Positional Params
- $epoch_timestamp
-
An explicit finish timestamp for the Span; if omitted, the current walltime is used implicitly.
Returns
The (finished) span itself, for chaining purposes.
set_tag( $tag_key, $string | $boolean | $number )
Adds a tag to the span
$span->set_tag( $tag_key => $tag_value );If there is a pre-existing tag set for tag_key, it is overwritten.
As an implementor, consider using "standard tags" listed in OpenTracing.io
If the span is already finished, a warning should be logged.
Required Positional Parameters
- tag_key, as
Str -
OpenTracing does not enforce any limitations though.
- tag_value, as
Value -
Must be either a string, a boolean value, or a numeric type.
Returns
The span itself, for chaining purposes.
log_data
Adds a log record to the span
$span->log_data(
$log_key1 => $log_value1,
$log_key2 => $log_value2,
...
);Required Positional Parameters
Returns
The span itself, for chaining purposes.
set_baggage_item
Sets a key:value pair on this Span and its SpanContext that also propagates to descendants of this Span.
$span->set_bagagge_item(
$baggage_key => $baggage_value
);Baggage items are key:value string pairs that apply to the given Span, its SpanContext, and all Spans which directly or transitively reference the local Span. That is, baggage items propagate in-band along with the trace itself.
Baggage items enable powerful functionality given a full-stack OpenTracing integration (for example, arbitrary application data from a mobile app can make it, transparently, all the way into the depths of a storage system), and with it some powerful costs: use this feature with care.
Use this feature thoughtfully and with care. Every key and value is copied into every local and remote child of the associated Span, and that can add up to a lot of network and cpu overhead.
Required Positional Parameters
Returns
The span itself, for chaining purposes.
get_baggage_item
Returns either the corresponding baggage value, or undef when such a value was missing.
my $baggage_value = $span->get_baggage_item( $baggage_key );Required Positional Parameters
Returns
The value or undef when such a value was missing.