/ 
Log-Any-1.717
River stage three • 307 direct dependents • 813 total dependents
/ Log::Any::Proxy::WithStackTrace

NAME

Log::Any::Proxy::WithStackTrace - Log::Any proxy to upgrade string errors to objects with stack traces

VERSION

version 1.717

SYNOPSIS

use Log::Any qw( $log, proxy_class => 'WithStackTrace' );

# Allow stack trace call stack arguments to be logged:
use Log::Any qw( $log, proxy_class => 'WithStackTrace',
                       proxy_show_stack_trace_args => 1 );

# Configure some adapter that knows how to:
#  1) handle structured data, and
#  2) handle message objects which have a "stack_trace" method:
Log::Any::Adapter->set($adapter);

$log->error("Help!");   # stack trace gets automatically added,
                        # starting from this line of code

DESCRIPTION

Some log adapters, like Log::Any::Adapter::Sentry::Raven, are able to take advantage of being passed message objects that contain a stack trace. However if a stack trace is not available, and fallback logic is used to generate one, the resulting trace can be confusing if it begins relative to where the log adapter was called, and not relative to where the logging method was originally called.

With this proxy in place, if any logging method is called with a log message that is a non-reference scalar (i.e. a string), that log message will be upgraded into a Log::Any::MessageWithStackTrace object with a stack_trace method, and that method will return a trace relative to where the logging method was called. A string overload is provided on the object to return the original log message.

Additionally, any call stack arguments in the stack trace will be deleted before logging, to avoid accidentally logging sensitive data. This happens both for message objects that were auto-generated from string messages, as well as for message objects that were passed in directly (if they appear to have a stack trace method). This default argument scrubbing behavior can be turned off by specifying a true value for the proxy_show_stack_trace_args import flag.

Important: This proxy should be used with a Log::Any::Adapter that is configured to handle structured data. Otherwise the object created here will just get stringified before it can be used to access the stack trace.

METHODS

maybe_upgrade_with_stack_trace

@args = $self->maybe_upgrade_with_stack_trace(@args);

This is an internal-use method that will convert a non-reference scalar message into a Log::Any::MessageWithStackTrace object with a stack_trace method. A string overload is provided to return the original message.

Stack trace args are scrubbed out in case they contain sensitive data, unless the proxy_show_stack_trace_args option has been set.

maybe_delete_stack_trace_args

$self->maybe_delete_stack_trace_args($arg);

This is an internal-use method that, given a single argument that is a reference, tries to figure out whether the argument is an object with a stack trace, and if so tries to delete any stack trace args.

The logic is based on Devel::StackTrace::Extract.

It specifically looks for objects with a stack_trace method (which should catch anything that does StackTrace::Auto, including anything that does Throwable::Error), or a trace method (used by Exception::Class and Moose::Exception and friends).

It specifically ignores Mojo::Exception objects, because their stack traces don't contain any call stack args.

delete_args_from_stack_trace($trace)

$self->delete_args_from_stack_trace($trace)

To scrub potentially sensitive data from Devel::StackTrace arguments, this method deletes arguments from all of the Devel::StackTrace::Frame in the trace.

AUTHORS

  • Jonathan Swartz <swartz@pobox.com>

  • David Golden <dagolden@cpan.org>

  • Doug Bell <preaction@cpan.org>

  • Daniel Pittman <daniel@rimspace.net>

  • Stephen Thirlwall <sdt@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2017 by Jonathan Swartz, David Golden, and Doug Bell.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.