NAME

OpenTracing::Role::Span - Role for OpenTracing implementations.

SYNOPSIS

    package OpenTracing::Implementation::MyBackendService::Span;
    
    use Moo;
    
    ...
    
    with 'OpenTracing::Role::Span'
    
    1;

DESCRIPTION

This is a Role for OpenTracing implenetations that are compliant with the OpenTracing::Interface.

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).

IMPLEMENTED OPENTRACING METHODS

The following methods from OpenTracing::Interface have been implemented. See their documentation for more details.

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().

See "get_context" in OpenTracing::Interface::Span.

overwrite_operation_name

Changes the operation name.

See "overwrite_operation_name" in OpenTracing::Interface::Span.

finish

Sets the end timestamp and finalizes Span state.

See "finish" in OpenTracing::Interface::Span.

add_tag

Adds a tag to the span.

See "add_tag" in OpenTracing::Interface::Span.

add_tags

Adds multiple tags to the span at the same time

See "add_tags" in OpenTracing::Interface::Span.

get_tags

This will return a Hash of key/value pairs.

See "get_tags" in OpenTracing::Interface::Span.

log_data

Adds a log record to the span.

See "log_data" in OpenTracing::Interface::Span.

add_baggage_item

Sets a key:value pair on this Span and its SpanContext that also propagates to descendants of this Span.

See "add_baggage_item" in OpenTracing::Interface::Span.

add_baggage_items

Sets multiple baggage_items at once.

See "add_baggage_items" in OpenTracing::Interface::Span.

get_baggage_item

Returns either the corresponding baggage value, or undef when such a value was missing.

See "get_baggage_item" in OpenTracing::Interface::Span.

get_baggage_items

This will return a Hash of key/value pairs.

See "get_baggage_items" in OpenTracing::Interface::Span.

WARNING

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.

ATTRIBUTES

operation_name

A required Str Type value, for the operation name.

See get_operation_name and overwrite_operation_name.

start_time

A read-only PositiveOrZeroNum floatingpoint that defaults to the number of seconds since epoch.

finish_time

A PositiveOrZeroNum floatingpoint that can only be set by calling finish.

See finish and has_finished.

tags

An optional HashRef of Values that defaults to an empty hash reference.

See add_tag, add_tags, get_tag, and get_tags.

context

A required read-only SpanContext type.

Although a read-only, it will get swapped for a clone_with result when trying to add any baggage_item, since SpanContext is inmutable.

See get_context, add_baggage_item, and add_baggage_items.

child_of

A optional Span or SpanContext.

Note: this may not be the correct design and this attribute may disapear.

See parent_span_id.

on_finish

Maybe a CodeRef that will gets executed when finish gets called. Its only parameter, is the Span invocant itself.

Its usefulnes currently is for dealing with c<span> inside Tracer.

See finish.

ADDITONAL INSTANCE METHODS

These methods are just for the convenience building an implementation, and are not part of the OpenTracing Interface..

get_operation_name

The accessor for the operatation_name

Parameter(s)

none

Returns

Str

has_finished

The state wether or not finish has been called or not.

Parameter(s)

none

Returns

Bool

get_span_id

The identifier of the Span itself, through its span context.

Parameter(s)

none

Returns

Uuid

get_parent_span_id

The identifier of the parent Span

Parameter(s)

none

Returns

Uuid

is_root_span

Returns 'true' if this is the root span, that is, if there is no parent span id.

Parameter(s)

none

Returns

Boolean, according to perl

duration

The time (in seconds) between start and finish. This will croak when either start_time or finish_time has not been set yet.

Parameter(s)

none

Returns

Num number of seconds

epoch_floatingpoint

A helper method to make it explicit that the time is in floating point, and not the usual integer number of seconds since epoch.

Parameter(s)

none

Returns

Num number of seconds since epoch

SEE ALSO

OpenTracing::Types

Type constraints for checking Interfaces

OpenTracing::Interface::Span

A role that defines the Span interface

AUTHOR

Theo van Hoesel <tvanhoesel@perceptyx.com>

COPYRIGHT AND LICENSE

'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.

cpanm OpenTracing::Role

perl -MCPAN -e shell
install OpenTracing::Role