OpenTracing::WrapScope - Automatically add spans to selected subroutines
use OpenTracing::WrapScope qw/foo Foo::bar/; use Foo; sub foo { ... } package Foo { sub bar { ... } }
or:
use OpenTracing::WrapScope; OpenTracing::WrapScope::install_wrapped('foo'); OpenTracing::WrapScope::install_wrapped('Foo::Bar');
which is roughly equivalent to:
use OpenTracing::AutoScope; sub foo { OpenTracing::AutoScope->start_guarded_span(); ... } package Foo { sub bar { OpenTracing::AutoScope->start_guarded_span(); ... } }
import takes subroutine names as arguments, these need to be fully qualified if they are not in the current package. All specified subroutines will have spans attached to them. Context and caller frames will be preserved.
The following tags will be automatically added to each span:
Additionally, if a wrapped subroutine dies, an additional error tag, containing the error message ($@) will be added to the span.
error
$@
List of subroutine names can be read from text files. Only a simple list of subroutines is supported with each line containing a single subroutine name, the subroutine needs to be fully qualified, regardless of where OpenTracing::WrapScope is used. The effect is the same as using the subroutine names directly. Multiple files can be specified at once.
Suppose you have a file called wrapscope.conf with the following contents:
wrapscope.conf
Foo::bar Foo::baz main::run
You could wrap these subroutines by using:
use OpenTracing::WrapScope -file => 'wrapscope.conf';
Mutiple filenames can be specified by using an arrayref:
use OpenTracing::WrapScope -file => [ 'config/wrap_base.conf', 'config/wrap_extra.conf' ];
or a shell glob (expanded using the glob builtin):
use OpenTracing::WrapScope -file => 'config/wrap*.conf';
If this argument is specified, arguments for -file will be read from OPENTRACING_WRAPSCOPE_FILE. This environment variable can contain a single filename/glob or multiple ones separated by colons:
OPENTRACING_WRAPSCOPE_FILE=wrapscope.conf OPENTRACING_WRAPSCOPE_FILE=config/wrap_base.conf:config/wrap_extra.conf OPENTRACING_WRAPSCOPE_FILE='config/wrap*.conf'
Replaces the specified subroutine with a span-handling version. $sub needs to be a fully qualified subroutine name or an unqualified name from the current package. The subroutine needs to be defined or a warning will be thrown. This warning can be made fatal with:
use warnings FATAL => 'OpenTracing::WrapScope';
or disabled with:
no warnings 'OpenTracing::WrapScope';
Returns a version of the given code reference with span handling attached. Useful for adding spans to anonymous subroutines.
Read a list of subroutines from $filename and install scope handlers in them. The file should contain a list of subroutines (identical to the one accepted by -file in import()).
-file
caller
Because this module overrides caller, it's best to use it as soon as possible, before caller-using code is compiled. It likely won't work well with other modules which override caller themselves.
Exporter
Subroutines exported using Exporter or a similar module could split into two versions. If the export happens before the span handling is applied to a subroutine, only the original version will have a span, the exported version will be unmodified.
In order to wrap subroutines in modules utilising Exporter, use OpenTracing::WrapScope directly in those modules.
Szymon Nieznanski <snieznanski@perceptyx.com>
'OpenTracing::WrapScope' is Copyright (C) 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.
To install OpenTracing::AutoScope, copy and paste the appropriate command in to your terminal.
cpanm
cpanm OpenTracing::AutoScope
CPAN shell
perl -MCPAN -e shell install OpenTracing::AutoScope
For more information on module installation, please visit the detailed CPAN module installation guide.