=head1 NAME OpenTracing::Interface::Span - A role that defines the Span interface =head1 SYNOPSIS pacakge OpenTracing::Implementation::MyBackendService::Span; sub get_context { ... } sub overwrite_operation_name { ... } sub finish { ... } sub add_tag { ... } sub add_tags { ... } sub get_tags { ... } sub log_data { ... } sub add_baggage_item { ... } sub add_baggage_items { ... } sub get_baggage_item { ... } sub get_baggage_items { ... } BEGIN { use Role::Tiny::With; with 'OpenTracing::Interface::Span' } # check at compile time, perl -c will work 1; =head1 DESCRIPTION This 'role' describes the interface for any OpenTracing Span implementation. C represents a unit of work executed on behalf of a trace. Examples of spans include a remote procedure call, or a in-process method call to a sub-component. Every span in a trace may have zero or more causal parents, and these relationships transitively form a DAG. It is common for spans to have at most one parent, and thus most traces are merely tree structures. =head1 INSTANCE METHODS =head2 C Yields the C for this C. Note that the return value of C is still valid after a call to L, as is a call to L after a call to L. my $span_context = $span->get_context; =over =item Parameter(s) =over I =back =item Returns =over =item C The current (possibly changed> span context. =back =back =head2 C Changes the operation name. $span->overwrite_operation_name( $operation_name ); =over =item Required Positional Parameter(s) =over =item operation_name, a B C The name of the span of work. =back =item Returns =over =item C The span itself, for chaining purposes. =back =back =head2 C Sets the end timestamp and finalizes Span state. $span->finish; or $span->finish( $epoch_timestamp ); With the exception of calls to C (which are always allowed), C 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. =over =item Optional Positional Param(s) =over =item epoch_timestamp, an B C An explicit finish timestamp for the span or, if omitted, the current walltime is used implicitly. =back =item Returns =over =item C The (finished) span object itself, for chaining purposes. =back =back =head2 C Adds a single tag to the span. $span->add_tag( $tag_key => $tag_value ); If there is a pre-existing tag set for C, it is overwritten. As an implementor, consider using "standard tags" listed at OpenTracing.io If the span has already finished, a warning should be logged. =over =item Required Positional Parameter(s) =over =item tag_key, a B C OpenTracing does not enforce any limitations though. =item tag_value, as B C Must be either a string, a boolean value, or a numeric type. =back =item Returns =over =item C The span itself, for chaining purposes. =back =back =head2 C Adds multiple tags to the span at the same time. $span->add_tags( $tag_key_1 => $tag_value_1, $tag_key_2 => $tag_value_2, ); See L<< C >> above. =head2 C This will return a Hash of key/value pairs. my %tags = $span->get_tags; It will return an empty list if there is no key/value pairs set. =over =item Positional Parameter(s) =over I =back =item Returns =over =item C A list of key/value pairs, not a hash reference! =back =back =head2 C Adds a log record to the span. $span->log_data( $log_key1 => $log_value1, $log_key2 => $log_value2, ... ); =over =item Cyclic Positional Parameter(s) =over =item key, as C =item $value, as C =back =item Returns =over =item C The span itself, for chaining purposes. =back =back =head2 C 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 C, its C, 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. =over =item Required Positional Parameter(s) =over =item baggage_key, as B C =item baggage_value, as C =back =item Returns =over =item C The span itself, for chaining purposes. =back =back =head2 C Sets multiple C at once. $span->set_bagagge_item( $baggage_key_1 => $baggage_value_1, $baggage_key_2 => $baggage_value_2, ); See L<< C >> above. =head2 C Returns either the corresponding baggage value, or C when such a value was missing. my $baggage_value = $span->get_baggage_item( $baggage_key ); =over =item Required Positional Parameters =over =item baggage_key, a B C =back =item Returns =over =item Maybe a C The value of the requested baggage item, or C when such a value was missing. =back =back =head2 C This will return a Hash of key/value pairs. my %baggage_items = $span->get_baggage_items; It will return an empty list if there is no key/value pairs set. =over =item Positional Parameter(s) =over I =back =item Returns =over =item C A list of key/value pairs, not a hash reference! =back =back =head1 SEE ALSO =over =item L Describes the API definition for OpenTransport implementations written in the Perl5 language. =item L A library of L type constraints that provides Duck Type checks for all common elements that conform L =back =head1 CAVEATS This description is using C 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. =head1 AUTHOR Theo van Hoesel =head1 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.