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.