perldoc > 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 AT pobox.com>

    *   David Golden <dagolden AT cpan.org>

    *   Doug Bell <preaction AT cpan.org>

    *   Daniel Pittman <daniel AT rimspace.net>

    *   Stephen Thirlwall <sdt AT 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.