view release on metacpan or  search on metacpan

lib/CGI/Application/Plugin/OpenTracing.pod  view on Meta::CPAN

    use OpenTracing::GlobalTracer qw/$TRACER/;

and later per subroutine:

    sub foo {
        my $opentracing_scope = $TRACER->start_active_span( foo => \%options );
        
        ...
        
        $opentracing_scope->close( )
    }

Alternatively, on can use L<OpenTracing::AutoScope>, which handles all the work
in one go:

    use OpenTracing::AutoScope;

and later per subroutine:

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

Lastly, use L<OpenTracing::Wrap>, to automagically wrap scopes and traces around
a list of mentioned (fully qualified) subroutine names.

=head1 FORMATTING TAGS

Query parameters and form-data fields will be added to the request span as tags.
For example, given a request URL:

    http://test-app.com/data?id=1&view=compact

The following tags would be added to the request span:

    'http.query.id'   => 1,
    'http.query.view' => 'compact',

However, if a parameter is repeated:

    http://test-app.com/data?id=1&id=2&id=3&view=compact

there would be multiple values for the C<http.query.id> tag.
OpenTracing span tags need to be scalars. The plugin will always turn
multiple values into a simple string. There are a few ways
to customize this behaviour.

By default, the parameter values are joined with the contents of
C<$CGI::Application::Plugin::TAG_JOIN_CHAR>, which is a comma by default.
Without any customization, the example above would yield the following tags:

    'http.query.id'   => '1,2,3',
    'http.query.view' => 'compact',

Simple join is often not enough and there are parameters which should
be skipped or obscured. The plugin allows to specify the formatting
with the following callbacks:

=over 4

=item opentracing_process_tags_query_params

Used to match and format URL query parameters (C<http.query.*> tags).

=item opentracing_process_tags_form_fields

Used to match and format form data fields (C<http.form.*> tags).

=item opentracing_process_tags

Used to match both query parameters and form data, when the specific
callbacks fail to match (see L<Fallbacks and matching order>).

=back

Their expected return values all follow the same format of key-value pairs
with an optional odd element at the end. For example:

    sub opentracing_process_tags_query_params {
        id           => sub { "[@_]" },
        location     => 'REDACTED',
        access_token => undef,
        sub { join ';', @_ },
    }

Each key represents a parameter name to match. The values define how
the parameter should be formatted. The last odd element is a fallback entry,
used to format parameters not matched elsewhere.

The values can be:

=over 4

=item undef - will cause the tag to be skipped altogether

=item string - will be used as the tag value directly

=item arrayref - will be joined with C<$CGI::Application::Plugin::TAG_JOIN_CHAR>

=item coderef - will be called with all values as arguments, and the return value will be used

=back

B<Note>: values returned by a coderef specification will be treated as
non-coderef formatters. For example, if a coderef formatter returns C<undef>,
the parameter will be skipped, if it returns an arrayref, it will be joined, etc.
It can't return another coderef.

Given the following example:

  http://test-app.com/data?id=1&id=2&id=3

  Specification        | http.query.id
  ---------------------+--------------
                       | 1,2,3
  id => undef          | 
  id => 'XXX'          | XXX
  id => [ 'X', 'Y' ]   | X,Y
  id => sub { "[@_]" } | [1 2 3]
  id => sub { \@_ }    | 1,2,3
  id => sub { undef }  |
  id => sub { 'XXX' }  | XXX

=head2 Matching multiple parameters

Sometimes, a single formatter fits multiple parameters:

  sub opentracing_process_tags {
      pwd      => undef,
      password => undef,
  }