.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Log::Any::Proxy::WithStackTrace 3pm"
.TH Log::Any::Proxy::WithStackTrace 3pm "2023-01-07" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Log::Any::Proxy::WithStackTrace \- Log::Any proxy to upgrade string errors to objects with stack traces
.SH "VERSION"
.IX Header "VERSION"
version 1.713
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Log::Any qw( $log, proxy_class => \*(AqWithStackTrace\*(Aq );
\&
\&  # Some adapter that knows how to handle both structured data,
\&  # and log messages which are actually objects with a
\&  # "stack_trace" method:
\&  #
\&  Log::Any::Adapter\->set($adapter);
\&
\&  $log\->error("Help!");   # stack trace gets automatically added
.Ve
.SH "DESCRIPTION"
.IX Header "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.
.PP
With this proxy in place, if any logging method is called with a message
that is a non-reference scalar, that message will be upgraded into a
\&\f(CW\*(C`Log::Any::MessageWithStackTrace\*(C'\fR object with a \f(CW\*(C`stack_trace\*(C'\fR 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 message.
.PP
\&\fBImportant:\fR 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.
.SH "METHODS"
.IX Header "METHODS"
.SS "maybe_upgrade_with_stack_trace"
.IX Subsection "maybe_upgrade_with_stack_trace"
This is an internal use method that will convert a non-reference scalar
message into a \f(CW\*(C`Log::Any::MessageWithStackTrace\*(C'\fR object with a
\&\f(CW\*(C`stack_trace\*(C'\fR method.  A string overload is provided to return the
original message.
.SH "AUTHORS"
.IX Header "AUTHORS"
.IP "\(bu" 4
Jonathan Swartz <swartz@pobox.com>
.IP "\(bu" 4
David Golden <dagolden@cpan.org>
.IP "\(bu" 4
Doug Bell <preaction@cpan.org>
.IP "\(bu" 4
Daniel Pittman <daniel@rimspace.net>
.IP "\(bu" 4
Stephen Thirlwall <sdt@cpan.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2017 by Jonathan Swartz, David Golden, and Doug Bell.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.