.\" Automatically generated by Pod::Man 2.1801 (Pod::Simple 3.05)
.\"
.\" 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" ''
'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 turned on, 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.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Log::Trace 3pm"
.TH Log::Trace 3pm "2005-11-24" "perl v5.10.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::Trace \- provides a unified approach to tracing
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 5
\&        # The tracing targets
\&        use Log::Trace; # No output
\&        use Log::Trace \*(Aqprint\*(Aq; # print to STDOUT
\&        use Log::Trace log => \*(Aq/var/log/foo.log\*(Aq; # Output to log file
\&        use Log::Trace print => { Level => 3 };
\&
\&        # Switch on/off logging with a constant
\&        use Log::Trace;
\&        import Log::Trace (\*(Aqlog\*(Aq => LOGFILE) if TRACING;
\&
\&
\&        # Set up tracing for all packages that advertise TRACE
\&        use Foo;
\&        use Bar;
\&        use Log::Trace warn => { Deep => 1 };
\&
\&        # Sets up tracing in all subpackages excluding Foo
\&        use Log::Trace warn => {Deep => 1, \*(AqExclude\*(Aq => \*(AqFoo\*(Aq};
\&
\&
\&        # Exported functions
\&        TRACE("Record this...");
\&        TRACE({Level => 2}, "Only shown if tracing level is 2 or higher");
\&        TRACEF("A la printf: %d\-%.2f", 1, 2.9999);
\&        TRACE_HERE();           # Record where we are (file, line, sub, args)
\&        DUMP(\e@loh, \e%hoh);     # Trace out via Data::Dumper
\&        DUMP("Title", \e@loh);   # Trace out via Data::Dumper
\&        my $dump = DUMP(@args); # Dump is returned without being traced
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
A module to provide a unified approach to tracing. A script can \f(CW\*(C`use
Log::Trace qw( < mode > )\*(C'\fR to set the behaviour of the \s-1TRACE\s0 function.
.PP
By default, the trace functions are exported to the calling package only. You
can export the trace functions to other packages with the \f(CW\*(C`Deep\*(C'\fR option. See
\&\*(L"\s-1OPTIONS\s0\*(R" for more information.
.PP
All exports are in uppercase (to minimise collisions with \*(L"real\*(R" functions).
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
.IP "\s-1TRACE\s0(@args)" 4
.IX Item "TRACE(@args)"
Output a message. Where the message actually goes depends on how you imported
Log::Trace (See \*(L"enabling Log::Trace\*(R"\*(L" in \*(R"Importing)
.Sp
The first argument is an optional hashref of options:
.Sp
.Vb 1
\&        TRACE(\*(AqA simple message\*(Aq);
.Ve
.Sp
vs:
.Sp
.Vb 1
\&        TRACE({ Level => 2.1 }, \*(AqA message at a specified trace level\*(Aq);
.Ve
.ie n .IP "\s-1TRACEF\s0($format, @args)" 4
.el .IP "\s-1TRACEF\s0($format, \f(CW@args\fR)" 4
.IX Item "TRACEF($format, @args)"
\&\f(CW\*(C`printf()\*(C'\fR equivalent of \s-1TRACE\s0. Also accepts an optional hashref:
.Sp
.Vb 2
\&        TRACEF(\*(Aq%d items\*(Aq, scalar @items);
\&        TRACEF({ Level => 5 }, \*(Aq$%1.2d\*(Aq, $value);
.Ve
.ie n .IP "\s-1DUMP\s0([$message,] @args)" 4
.el .IP "\s-1DUMP\s0([$message,] \f(CW@args\fR)" 4
.IX Item "DUMP([$message,] @args)"
Serialises each of \f(CW@args\fR, optionally prepended with \f(CW$message\fR. If called in a
non-void context, \s-1DUMP\s0 will return the serialised data rather than \s-1TRACE\s0
it. This is useful if you want to \s-1DUMP\s0 a datastructure at a specific tracing
level.
.Sp
.Vb 2
\&        DUMP(\*(Aqcolours\*(Aq, [qw(red green blue)]);             # outputs via TRACE
\&        my $dump = DUMP(\*(Aqcolours\*(Aq, [qw(red green blue)]);  # output returned
.Ve
.IP "\s-1\fITRACE_HERE\s0()\fR" 4
.IX Item "TRACE_HERE()"
TRACEs the current position on the call stack (file, line number, subroutine
name, subroutine args).
.Sp
.Vb 2
\&        TRACE_HERE();
\&        TRACE_HERE({Level => 99});
.Ve
.SH "Importing/enabling Log::Trace"
.IX Header "Importing/enabling Log::Trace"
.IP "import($target, [$arg], [\e%params])" 4
.IX Item "import($target, [$arg], [%params])"
Controls where \s-1TRACE\s0 messages go. This method is called automatically when you
call \f(CW\*(Aquse Log::Trace;\*(Aq\fR, but you may explicitly call this method at
runtime. Compare the following:
.Sp
.Vb 1
\&        use Log::Trace \*(Aqprint\*(Aq;
.Ve
.Sp
which is the same as
.Sp
.Vb 4
\&        BEGIN {
\&                require Log::Trace;
\&                Log::Trace\->import(\*(Aqprint\*(Aq);
\&        }
.Ve
.Sp
Valid combinations of \f(CW$target\fR and \f(CW\*(C`arg\*(C'\fR are:
.RS 4
.ie n .IP "print => $filehandle" 4
.el .IP "print => \f(CW$filehandle\fR" 4
.IX Item "print => $filehandle"
Prints trace messages to the supplied \f(CW$filehandle\fR. Defaults to \f(CW\*(C`STDOUT\*(C'\fR
if no file handle is specified.
.IP "warn" 4
.IX Item "warn"
Prints trace messages via \f(CW\*(C`warn()\*(C'\fRs to \f(CW\*(C`STDERR\*(C'\fR.
.IP "buffer => \e$buffer" 4
.IX Item "buffer => $buffer"
Appends trace messages to a string reference.
.ie n .IP "file => $filename" 4
.el .IP "file => \f(CW$filename\fR" 4
.IX Item "file => $filename"
Append trace messages to a file. If the file doesn't exist, it will be created.
.ie n .IP "log => $filename" 4
.el .IP "log => \f(CW$filename\fR" 4
.IX Item "log => $filename"
This is equivalent to:
.Sp
.Vb 1
\&        use Log::Trace file => $filename, {Verbose => 2};
.Ve
.ie n .IP "syslog => $priority" 4
.el .IP "syslog => \f(CW$priority\fR" 4
.IX Item "syslog => $priority"
Logs trace messages to syslog via \f(CW\*(C`Sys::Syslog\*(C'\fR, if available.
.Sp
You should consult your syslog configuration before using this option.
.Sp
The default \f(CW$priority\fR is '\f(CW\*(C`debug\*(C'\fR', and the \f(CW\*(C`ident\*(C'\fR is set to
\&\f(CW\*(C`Log::Trace\*(C'\fR. You can configure the \f(CW\*(C`priority\*(C'\fR, but beyond that, you can
implement your own syslogging via the \f(CW\*(C`custom\*(C'\fR trace target.
.IP "custom => \e&custom_trace_sub" 4
.IX Item "custom => &custom_trace_sub"
Trace messages are processed by a custom subroutine. E.g.
.Sp
.Vb 1
\&        use Log::Trace custom => \e&mylogger;
\&
\&        sub mylogger {
\&                my @messages = @_;
\&                foreach (@messages) {
\&                        # highly sensitive trace messages!
\&                        tr/a\-zA\-Z/n\-za\-mN\-ZA\-M/;
\&                        print;
\&                }
\&        }
.Ve
.RE
.RS 4
.Sp
The import \f(CW\*(C`\e%params\*(C'\fR are optional. These two statements are functionally the
same:
.Sp
.Vb 2
\&        import Log::Trace print => {Level => undef};
\&        import Log::Trace \*(Aqprint\*(Aq;
.Ve
.Sp
See \*(L"\s-1OPTIONS\s0\*(R" for more information.
.Sp
\&\fBNote:\fR If you use the \f(CW\*(C`custom\*(C'\fR tracing option, you should be careful about
supplying a subroutine named \f(CW\*(C`TRACE\*(C'\fR.
.RE
.SH "OPTIONS"
.IX Header "OPTIONS"
.IP "AllSubs => \s-1BOOL\s0" 4
.IX Item "AllSubs => BOOL"
Attaches a \f(CW\*(C`TRACE\*(C'\fR statement to all subroutines in the package. This can be
used to track the execution path of your code. It is particularly useful when
used in conjunction with \f(CW\*(C`Deep\*(C'\fR and \f(CW\*(C`Everywhere\*(C'\fR options.
.Sp
\&\fBNote:\fR Anonymous subroutines and \f(CW\*(C`AUTOLOAD\*(C'\fR are not \f(CW\*(C`TRACE\*(C'\fRd.
.IP "AutoImport => \s-1BOOL\s0" 4
.IX Item "AutoImport => BOOL"
By default, \f(CW\*(C`Log::Trace\*(C'\fR will only set up \f(CW\*(C`TRACE\*(C'\fR routines in modules that
have already been loaded. This option overrides \f(CW\*(C`require()\*(C'\fR so that modules
loaded after \f(CW\*(C`Log::Trace\*(C'\fR can automatically be set up for tracing.
.Sp
\&\fBNote\fR: This is an experimental feature. See the \s-1ENVIRONMENT\s0 \s-1NOTES\s0
for information about behaviour under different versions of perl.
.Sp
This option has no effect on perl < 5.6
.IP "Deep => \s-1BOOL\s0" 4
.IX Item "Deep => BOOL"
Attaches \f(CW\*(C`Log::Trace\*(C'\fR to all packages (that define a \s-1TRACE\s0 function). Any
\&\s-1TRACEF\s0, \s-1DUMP\s0 and \s-1TRACE_HERE\s0 routines will also be overridden in these packages.
.IP "Dumper => Data::Serializer backend" 4
.IX Item "Dumper => Data::Serializer backend"
Specify a serialiser to be used for DUMPing data structures.
.Sp
This should either be a string naming a Data::Serializer backend (e.g. \*(L"\s-1YAML\s0\*(R") 
or a hashref of parameters which will be passed to Data::Serializer, e.g.
.Sp
.Vb 6
\&        {
\&                serializer => \*(AqXML::Dumper\*(Aq,
\&                options => {
\&                        dtd => \*(Aqpath/to/my.dtd\*(Aq
\&                }
\&        }
.Ve
.Sp
Note that the \fIraw_serialise()\fR method of Data::Serializer is used.  See Data::Serializer
for more information.
.Sp
If you do not have \f(CW\*(C`Data::Serializer\*(C'\fR installed, leave this option undefined to use the
\&\f(CW\*(C`Data::Dumper\*(C'\fR natively.
.Sp
Default: undef (use standalone Data::Dumper)
.IP "Everywhere => \s-1BOOL\s0" 4
.IX Item "Everywhere => BOOL"
When used in conjunction with the \f(CW\*(C`Deep\*(C'\fR option, it will override the
standard behaviour of only enabling tracing in packages that define \f(CW\*(C`TRACE\*(C'\fR
stubs.
.Sp
Default: false
.IP "Exclude => STRING|ARRAY" 4
.IX Item "Exclude => STRING|ARRAY"
Exclude a module or list of modules from tracing.
.IP "Level => NUMBER|LIST|CODE" 4
.IX Item "Level => NUMBER|LIST|CODE"
Specifies which trace levels to display.
.Sp
If no \f(CW\*(C`Level\*(C'\fR is defined, all \s-1TRACE\s0 statements will be output.
.Sp
If the value is numeric, only TRACEs that are at the specified level or below
will be output.
.Sp
If the value is a list of numbers, only TRACEs that match the specified levels
are output.
.Sp
The level may also be a code reference which is passed the package name and the
\&\s-1TRACE\s0 level. It mst return a true value if the \s-1TRACE\s0 is to be output.
.Sp
Default: undef
.IP "Match => \s-1REGEX\s0" 4
.IX Item "Match => REGEX"
Exports trace functions to packages that match the supplied regular
expression. Can be used in conjunction with  \f(CW\*(C`Exclude\*(C'\fR. You can also use
\&\f(CW\*(C`Match\*(C'\fR as an exclusion method if you give it a negative look-ahead.
.Sp
For example:
.Sp
.Vb 1
\&        Match => qr/^(?!Acme::)/  # will exclude every module beginning with Acme::
.Ve
.Sp
and
.Sp
.Vb 1
\&        Match => qr/^Acme::/      # does the reverse
.Ve
.Sp
Default: '.' # everything
.IP "Verbose => 0|1|2" 4
.IX Item "Verbose => 0|1|2"
You can use this option to prepend extra information to each trace message. The
levels represent increasing levels of verbosity:
.Sp
.Vb 3
\&        0: the default*, don\*(Aqt add anything
\&        1: adds subroutine name and line number to the trace output
\&        2: As [1], plus a filename and timestamp (in ISO 8601 : 2000 format)
.Ve
.Sp
This setting has no effect on the \f(CW\*(C`custom\*(C'\fR or \f(CW\*(C`log\*(C'\fR targets.
.Sp
* \fIthe log target uses 'Verbose' level 2\fR
.SH "ENVIRONMENT NOTES"
.IX Header "ENVIRONMENT NOTES"
The AutoImport feature overrides \f(CW\*(C`CORE::require()\*(C'\fR which requires perl 5.6, but you may see unexpected errors if you aren't using at
least perl 5.8. The AutoImport option has no effect on perl < 5.6.
.PP
In mod_perl or other persistent interpreter environments, different applications could trample on each other's
\&\f(CW\*(C`TRACE\*(C'\fR routines if they use Deep (or Everywhere) option.  For example application A could route all the trace output 
from Package::Foo into \*(L"appA.log\*(R" and then application B could import Log::Trace over the top, re-routing all the trace output from Package::Foo
to \*(L"appB.log\*(R" for evermore.  One way around this is to ensure you always import Log::Trace on every run in a persistent environment from all your 
applications that use the Deep option.  We may provide some more tools to work around this in a later version of \f(CW\*(C`Log::Trace\*(C'\fR.
.PP
\&\f(CW\*(C`Log::Trace\*(C'\fR has not been tested in a multi-threaded application.
.SH "DEPENDENCIES"
.IX Header "DEPENDENCIES"
.Vb 5
\&        Carp
\&        Time::HiRes      (used if available)
\&        Data::Dumper     (used if available \- necessary for meaningful DUMP output)
\&        Data::Serializer (optional \- to customise DUMP output)
\&        Sys::Syslog      (loaded on demand)
.Ve
.SH "RELATED MODULES"
.IX Header "RELATED MODULES"
.IP "Log::TraceMessages" 4
.IX Item "Log::TraceMessages"
\&\f(CW\*(C`Log::TraceMessages\*(C'\fR is similar in design and purpose to \f(CW\*(C`Log::Trace\*(C'\fR.
However, it only offers a subset of this module's functionality. Most notably,
it doesn't offer a mechanism to control the tracing output of an entire
application \- tracing must be enabled on a module-by-module
basis. \f(CW\*(C`Log::Trace\*(C'\fR also offers control over the output with the trace
levels and supports more output targets.
.IP "Log::Agent" 4
.IX Item "Log::Agent"
\&\f(CW\*(C`Log::Agent\*(C'\fR offers a procedural interface to logging. It strikes a good
balance between configurability and ease of use. It differs to \f(CW\*(C`Log::Trace\*(C'\fR in
a number of ways. \f(CW\*(C`Log::Agent\*(C'\fR has a concept of channels and priorities, while
\&\f(CW\*(C`Log::Trace\*(C'\fR only offers levels. \f(CW\*(C`Log::Trace\*(C'\fR also supports tracing code
execution path and the \f(CW\*(C`Deep\*(C'\fR import option. \f(CW\*(C`Log::Trace\*(C'\fR trades a certain
amount of configurability for increased ease-of use.
.IP "Log::Log4Perl" 4
.IX Item "Log::Log4Perl"
A feature rich perl port of the popular \f(CW\*(C`log4j\*(C'\fR library for Java. It is
object-oriented and comprised of more than 30 modules. It has an impressive
feature set, but some people may be frightened of its complexity. In contrast,
to use \f(CW\*(C`Log::Trace\*(C'\fR you need only remember up to 4 simple functions and a
handful of configuration options.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Log::Trace::Manual \- A guide to using Log::Trace
.SH "VERSION"
.IX Header "VERSION"
\&\f(CW$Revision:\fR 1.70 $ on \f(CW$Date:\fR 2005/11/01 11:32:59 $ by \f(CW$Author:\fR colinr $
.SH "AUTHOR"
.IX Header "AUTHOR"
John Alden and Simon Flack with some additions by Piers Kent and Wayne Myers 
<cpan _at_ bbc _dot_ co _dot_ uk>
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
(c) \s-1BBC\s0 2005. This program is free software; you can redistribute it and/or modify it under the \s-1GNU\s0 \s-1GPL\s0.
.PP
See the file \s-1COPYING\s0 in this distribution, or http://www.gnu.org/licenses/gpl.txt