=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 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;



=head1 DESCRIPTION

This 'role' describes the interface for any OpenTracing Span implementation.

C<Span> 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 get_context

Yields the C<SpanContext> for this C<Span>. Note that the return value of 
C<get_context()> is still valid after a call to L<finish()>, as is a call to
L<get_context()> after a call to L<finish()>.

    my $span_context = $span->get_context;


=head3 Parameters

none

=head3 Returns

An object of type C<SpanContext> from L<OpenTracing::Types>.



=head2 overwrite_operation_name( $operation_name )

Changes the operation name.

    $span->overwrite_operation_name( $operation_name );

=head3 Required Positional Parameters

=over

=item operation_name

The name of the operation-name, must be a string.

=back

=head3 Returns

The span itself, for chaining purposes.



=head2 finish( <none> | $epoch_timestamp )

Sets the end timestamp and finalizes Span state.

    $span->finish;

or

    $span->finish( $epoch_timestamp );

With the exception of calls to C<get_context()> (which are always allowed),
C<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.

=head3 Optional Positional Params

=over

=item $epoch_timestamp

An explicit finish timestamp for the C<Span>; if omitted, the current walltime
is used implicitly.

=back

=head3 Returns

The (finished) C<Span> itself, for chaining purposes.



=head2 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 C<tag_key>, it is overwritten.

As an implementor, consider using "standard tags" listed in OpenTracing.io

If the C<Span> is already finished, a warning should be logged.

=head3 Required Positional Parameters

=over

=item tag_key, as C<Str>

OpenTracing does not enforce any limitations though.

=item tag_value, as C<Value>

Must be either a string, a boolean value, or a numeric type.

=back

=head3 Returns

The span itself, for chaining purposes.



=head2 log_data( $key => $value .. )

Adds a log record to the span

    $span->log_data(
        $log_key1 => $log_value1,
        $log_key2 => $log_value2,
        ...
    );

=head3 Required Positional Parameters

=over

=item key, as C<Str>

=item value, as C<Str>

=back

=head3 Returns

The span itself, for chaining purposes.



=head2 set_baggage_item( $key => $value )

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<Span>, its
C<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.

=head3 Required Positional Parameters

=over

=item baggage_key, as C<Str>

=item baggage_value, as C<Value>

=back

=head3 Returns

The span itself, for chaining purposes.



=head2 get_baggage_item( $key )

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

    my $baggage_value = $span->get_baggage_item( $baggage_key );

=head3 Required Positional Parameters

=over

=item baggage_key, as C<Str>

=back

=head3 Returns

The value or C<undef> when such a value was missing.

=cut



=head1 SEE ALSO

=over

=item L<OpenTracing::Interface>

Describes the API definition for OpenTransport implementations written in the
Perl5 language.

=item L<OpenTracing::Types>

A library of L<Type::Tiny> type constraints that provides Duck Type checks for
all common elements that conform L<OpenTracing::Interface>

=back

=cut



=head1 CAVEATS

This description is using C<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.

=cut
