=head1 NAME

OpenTracing::AutoScope - Automagically create and close scoped spans.



=head1 SYNOPSIS

    MyPackage;
    
    use OpenTracing::AutoScope;
    
    sub foo {
        OpenTracing::AutoScope->start_guarded_span;
        
        ...
        
    }



=head1 DESCRIPTION

Using the C<start_guarded_span> class method is just a convenience around things
like:

    use OpenTracing::GlobalTracer qw/$TRACER/;
    
    sub foo {
        my $scope = $TRACER->start_active_span( 'MyPackage::foo' => { options };
        
        my $self = shift;
        
        ... # do stuff
        
        $scope->close
        
        return $foo
    }



OpenTracing provides an instance method for a C<$tracer>, called
C<start_active_span> and returns a scope object. But scope object, according to
the API spec needs to be closed by the programmer and it will issue a warning if
not done so.

But that strategy becomes very inconvenient if a programmer wants to do 'return
early' or bail out half way because of some other conditions.

This being Perl, we can do better and use the features that would normally come
on the end of scope and could use a C<DESTROY> or C<DEMOLISH> method. But that
would still send out a warning.

This module will make it easy again, and a bit more. It will call C<close> on
the relevant scope it has created automagically.

It will also use the subroutine name as the operation name, that otherwise would
be required.



=head1 CLASS METHODS



=head2 start_guarded_span

Starts a scope guarded span which will automagically get closed once the process
runs out of the current scope. It returns nothing, in order to prevent programmers
from explicitly closing the returned scope.

It does not need an operation_name, it will default to the current subroutine
name. Other than that, it accepts any or all of the options for
C<< $TRACER->start_active_span >>. 



=head1 AUTHOR

Theo van Hoesel <tvanhoesel@perceptyx.com>



=head1 COPYRIGHT AND LICENSE

'OpenTracing::AutoScope' 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 package 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.


=cut
