=head1 NAME

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

=head1 SYNOPSIS

    package OpenTracing::Implementation::MyBackendService::Tracer;
    
    sub get_scope_manager {
        ...
    }
    
    sub get_active_span {
        ...
    }
    
    sub start_active_span {
        ...
    }
    
    sub start_span {
        ...
    }
    
    sub inject_context {
        ...
    }
    
    sub extract_context {
        ...
    }
    
    BEGIN {
        use Role::Tiny::With;
        with 'OpenTracing::Interface::Tracer'
    } # check at compile time, perl -c will work
    
    1;



=head1 DESCRIPTION

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

Tracer is the entry point API between instrumentation code and the tracing
implementation.


=head1 INSTANCE METHODS



=head2 C<get_scope_manager>

Returns the current C<ScopeManager>, which may be a 'NoOp' implementation but
may not be C<undef>.

    my $scope_manager = $tracer->get_scope_manager;

=over

=item Positional Parameter(s)

=over

I<none>

=back

=item Returns

=over

=item C<ScopeManager>

The scope manager dealing with scope for the integration.

This will return a instance of aL<< C<NoOp> Implementation|
OpenTracing::Implementation::NoOp::ScopeManager >> if no scope manager has been
given during instantiation!

=back

=back



=head2 C<get_active_span>

This will return the 'active' span.

    my $span = $tracer->get_active_span;

A shorthand for C<< $tracer->get_scope_manager->get_active_scope->get_span >>.

=over

=item Positional Parameter(s)

=over

I<none>

=back

=item Returns

=over

=item Maybe C<Span>

An span object or C<undef> if there is no active scope.

=back

=back



=head2 C<start_active_span>

Starts AND activates a C<Span> and returns its C<Scope>.

    my $scope = $tracer->start_active_span( 'some work needs to be done',
        child_of                => $span_context,
        references              => [
            ContextReference->new_follows_from( $some_context ),
        ],
        tags                    => {
            tag_key_1               => 'tag_value_1',
        },
        start_time              => time,            # default
        ignore_active_span      => 0,               # default
        finish_span_on_close    => 1,               # default
    );

=over

=item Required Positional Parameter(s)

=over

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

=back

=item Named Options

=over

=item C<child_of>, a C<Span> or C<SpanContext>

either

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

or

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

=item C<references>, as B<array reference> of C<ContextReference>s

=item C<tags>, a B<hash reference> of C<Str>

a hash reference of tags, the values must be a strings.

=item C<start_time>, a C<PositiveOrZeroNum>

The (fractional) number off  seconds since epoch, and can have decimals, for
example, up to nano-seconds accuracy.

=item C<ignore_active_span>, a C<Bool>

When set to 'true', will not use the current active span when creating an
implicit parent span for a missing C<child_of>, otherwise, that would be
used.

=item C<finish_span_on_close>, a C<Bool>

When set to false, it will not be automatically closed when it goes out of
scope. This is 'true' by default.

=back

=item Returns

=over

=item C<Scope>

=back

=item Note

C<child_of> and C<references> are mutual exclusive.

=back



=head2 C<start_span>

Starts, but does not activate a C<Span>

    my $scope = $tracer->start_active_span( 'some work needs to be done',
        child_of                => $span_context,
        references              => [
            ContextReference->new_follows_from( $some_context ),
        ],
        tags                    => {
            tag_key_1               => 'tag_value_1',
        },
        start_time              => time,            # default
        ignore_active_span      => 0,               # default
    );

=over

=item Required Positional Parameter(s)

=over

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

=back

=item Named Options

=over

=item C<child_of>, a C<Span> or C<SpanContext>

either

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

or

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

=item C<references>, as B<array reference> of C<ContextReference>s

=item C<tags>, a B<hash reference> of C<Str>

a hash reference of tags, the values must be a strings.

=item C<start_time>, a C<PositiveOrZeroNum>

The (fractional) number off  seconds since epoch, and can have decimals, for
example, up to nano-seconds accuracy.

=item C<ignore_active_span>, a C<Bool>

When set to 'true', will not use the current active span when creating an
implicit parent span for a missing C<child_of>, otherwise, that would be
used.

=back

=item Returns

=over

=item C<Span>

=back

=item Note

C<child_of> and C<references> are mutual exclusive.

=back



=head2 C<inject_context>

Takes a C<SpanContext> and takes the bits that are of interest, and injects them
into a B<cloned> carrier.

    my $span_context = $tracer->get_active_span->get_context;
    
    use HTTP::Headers;
    my $http_headers = HTTP::Headers->new( ... );
    
    my $cntx_headers =
        $tracer->inject_context( $http_headers, $opentracing_spancontext );
    
    my $request = HTTP::Request->new(
        GET => 'https://...', $cntx_headers
    );
    my response = LWP::UserAgent->request( $request );

The C<$carier> will be a best effort clone, because immutable object should be
the right thing to have.

Depending on the implementation items that will be injected are things like
C<trace_id>, C<span_id> and possibly all the C<baggage_items>.

=over

=item Required Positional Parameter(s)

=over

=item carrier

Most likely, a 'object' but a plain array or hash reference should be acceptable
too and will have the implementation specific key/value pairs added. 

=back

=item Optional Positional Parameter(s)

=over

=item span_context, An B<optional> C<SpanContext>

The span context containing the the information that needs to be added to the
carrier.

If omited, the context of the active span will be used.

=back

=item Returns

=over

=item C<Object> or otherwise <Defined>

A B<cloned> version of the carrier with the - for the implementation relevent -
injected context items.

=back

=back



=head2 C<extract_context>

Extract the tracer relevant information from a C<$carrier> and return it as a
C<SpanContext>.

    get '/some_service' => sub {
        my $http_headers = YourFramework->request->headers;
        
        my $opentracing_context = $TRACER->extract_context( $http_headers );
        
        ...
        
    }

This may return C<undef> iff the carrier can be understood, and no relevant
information could be detected. This usually happens at incomming request that
are not part of a ditributed service.

=over

=item Required Positional Parameter(s)

=over

=item carrier

Most likely, a 'object' but a plain array or hash reference containing
implementation specific key/value pairs should be acceptable too. 

=back

=item Returns

=over

=item Maybe C<SpanContext>

=back

=back



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