=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 {
        ...
    }
    
    BEGIN {
        use Role::Tiny::With;
        with 'OpenTracing::Interface::Tracer'
            if $ENV{OPENTRACING_INTERFACE};
    } # check at compile time, perl -c will work
    
    1;



=head1 DESCRIPTION

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

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 METHODS



=head2 get_scope_manager

Returns the current L<ScopeManager>, which may be a noop but may not be null.



=head2 get_active_span

This will return the 'active' span.

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

It will return C<undef> if there is no active scope.



=head2 start_active_span

=head3 Required Positional Parameters

=over

=item operation_name, as C<Str>

=back

=head3 Optional Dictionairy with Named Options

=over

=item child_of

either

an object that does L<OpenTracing::Interface::Span>

or

an object that does L<OpenTracing::Interface::SpanContext>

=item references

an C<ArrayRef> of 'references' ... # XXX Don't ask me now!

=item tags

a C<HashRef> of tags, the values must be a C<Str>

=item start_time

A C<Num>, that is the number off seconds since epoch, and can have decimals, for
example, up to nana-seconds accuracy

=item 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 L<child_of>, otherwise, that would be
used.

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

=head3 Returns

An object that implements the L<Scope> interface.



=head2 start_span

=head3 Required Positional Parameters

=over

=item operation_name, as C<Str>

=back

=head3 Optional Dictionairy with Named Options

=over

=item child_of

either

an object that does L<OpenTracing::Interface::Span>

or

an object that does L<OpenTracing::Interface::SpanContext>

=item references

an C<ArrayRef> of 'references' ... # XXX Don't ask me now!

=item tags

a C<HashRef> of tags, the values must be a C<Str>

=item start_time

A C<Num>, that is the number off seconds since epoch, and can have decimals, for
example, up to nana-seconds accuracy

=item 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 L<child_of>, otherwise, that would be
used.

=back

=head3 Returns

An object that implements the L<OpenTracing::Interface::Span> interface.


=cut
