
=head1 NAME

OpenTracing::Interface::SpanContext - A role that defines the SpanContext interface



=head1 SYNOPSIS

    package OpenTracing::Implementation::MyBackendService::SpanContext;
    
    sub get_baggage_item {
        ...
    }
    
    sub get_baggage_items {
        ...
    }
    
    sub with_baggage_item {
        ...
    }
    
    sub with_baggage_items {
        ...
    }
    
    BEGIN {
        use Role::Tiny::With;
        with 'OpenTracing::Interface::SpanContext'
            if $ENV{OPENTRACING_INTERFACE};
    } # check at compile time, perl -c will work
    
    1;



=head1 DESCRIPTION

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

SpanContext represents C<Span> state that must propagate to descendant C<Span>'s
and across process boundaries.

SpanContext is logically divided into two pieces: the user-level "Baggage" (see
L<with_baggage_item> and L<get_baggage_item>) that propagates across C<Span>
boundaries and any tracer-implementation-specific fields that are needed to
identify or otherwise contextualize the associated L<Span> (e.g., a C<trace_id>,
C<span_id>, C<sampled>).



=head1 INSTANCE METHODS



=head2 C<get_baggage_item>

This will return the value of a baggage item, based on its key.

    my $value = $span_context->get_baggage_item( 'baggage_key' );

It will return C<undef> if there is no value for the given key.

=over

=item Required Positional Parameter(s)

=over

=item baggage_key, a B<required> C<Str>

=back

=item Returns

=over

=item Maybe a C<Value>

The value of the requested baggage item, or C<undef> when such a value was
missing.

=back

=back



=head2 C<get_baggage_items>

This will return a Hash of key/value pairs.

    my %items = $span_context->get_baggage_items;

It will return an empty list if there is no key/value pairs set.

=over

=item Positional Parameter(s)

=over

I<none>

=back

=item Returns

=over

=item C<Hash>

A list of key/value pairs, not a hash reference!

=back

=back



=head2 C<with_baggage_item>

Creates a cloned C<SpanContext> object with the new key => value pair.

    my $new_span_context = $old_span_context->with_baggage_item(
        baggage_key => $value,
    );

=over

=item Required Positional Parameter(s)

=over

=item baggage_key, as B<required> C<Str>

=item baggage_value, as C<Value>

=back

=item Returns

=over

=item C<SpanContext>

A b<cloned> version of the invocing span context for chaining purposes.

=back 

=back



=head2 C<with_baggage_items>

Creates a cloned C<SpanContext> object with the multiple key => value pairs.

    my $new_span_context = $old_span_context->with_baggage_items(
        baggage_key => $value,
        another_key => $other,
    );

See L<< C<with_baggage_item> >> above.



=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



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



=head1 AUTHOR

Theo van Hoesel <tvanhoesel@perceptyx.com>



=head1 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.
