Log::Trace(3) User Contributed Perl Documentation Log::Trace(3)NAMELog::Trace - provides a unified approach to tracing
SYNOPSIS
# The tracing targets
use Log::Trace; # No output
use Log::Trace 'print'; # print to STDOUT
use Log::Trace log => '/var/log/foo.log'; # Output to log file
use Log::Trace print => { Level => 3 };
# Switch on/off logging with a constant
use Log::Trace;
import Log::Trace ('log' => 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, 'Exclude' => 'Foo'};
# 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(\@loh, \%hoh); # Trace out via Data::Dumper
DUMP("Title", \@loh); # Trace out via Data::Dumper
my $dump = DUMP(@args); # Dump is returned without being traced
DESCRIPTION
A module to provide a unified approach to tracing. A script can "use
Log::Trace qw( < mode > )" to set the behaviour of the TRACE function.
By default, the trace functions are exported to the calling package
only. You can export the trace functions to other packages with the
"Deep" option. See "OPTIONS" for more information.
All exports are in uppercase (to minimise collisions with "real"
functions).
FUNCTIONS
TRACE(@args)
Output a message. Where the message actually goes depends on how
you imported Log::Trace (See "enabling Log::Trace"" in "Importing)
The first argument is an optional hashref of options:
TRACE('A simple message');
vs:
TRACE({ Level => 2.1 }, 'A message at a specified trace level');
TRACEF($format, @args)
"printf()" equivalent of TRACE. Also accepts an optional hashref:
TRACEF('%d items', scalar @items);
TRACEF({ Level => 5 }, '$%1.2d', $value);
DUMP([$message,] @args)
Serialises each of @args, optionally prepended with $message. If
called in a non-void context, DUMP will return the serialised data
rather than TRACE it. This is useful if you want to DUMP a
datastructure at a specific tracing level.
DUMP('colours', [qw(red green blue)]); # outputs via TRACE
my $dump = DUMP('colours', [qw(red green blue)]); # output returned
TRACE_HERE()
TRACEs the current position on the call stack (file, line number,
subroutine name, subroutine args).
TRACE_HERE();
TRACE_HERE({Level => 99});
Importing/enabling Log::Trace
import($target, [$arg], [\%params])
Controls where TRACE messages go. This method is called
automatically when you call 'use Log::Trace;', but you may
explicitly call this method at runtime. Compare the following:
use Log::Trace 'print';
which is the same as
BEGIN {
require Log::Trace;
Log::Trace->import('print');
}
Valid combinations of $target and "arg" are:
print => $filehandle
Prints trace messages to the supplied $filehandle. Defaults to
"STDOUT" if no file handle is specified.
warn
Prints trace messages via "warn()"s to "STDERR".
buffer => \$buffer
Appends trace messages to a string reference.
file => $filename
Append trace messages to a file. If the file doesn't exist, it
will be created.
log => $filename
This is equivalent to:
use Log::Trace file => $filename, {Verbose => 2};
syslog => $priority
Logs trace messages to syslog via "Sys::Syslog", if available.
You should consult your syslog configuration before using this
option.
The default $priority is '"debug"', and the "ident" is set to
"Log::Trace". You can configure the "priority", but beyond
that, you can implement your own syslogging via the "custom"
trace target.
custom => \&custom_trace_sub
Trace messages are processed by a custom subroutine. E.g.
use Log::Trace custom => \&mylogger;
sub mylogger {
my @messages = @_;
foreach (@messages) {
# highly sensitive trace messages!
tr/a-zA-Z/n-za-mN-ZA-M/;
print;
}
}
The import "\%params" are optional. These two statements are
functionally the same:
import Log::Trace print => {Level => undef};
import Log::Trace 'print';
See "OPTIONS" for more information.
Note: If you use the "custom" tracing option, you should be careful
about supplying a subroutine named "TRACE".
OPTIONS
AllSubs => BOOL
Attaches a "TRACE" 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 "Deep" and
"Everywhere" options.
Note: Anonymous subroutines and "AUTOLOAD" are not "TRACE"d.
AutoImport => BOOL
By default, "Log::Trace" will only set up "TRACE" routines in
modules that have already been loaded. This option overrides
"require()" so that modules loaded after "Log::Trace" can
automatically be set up for tracing.
Note: This is an experimental feature. See the ENVIRONMENT NOTES
for information about behaviour under different versions of perl.
This option has no effect on perl < 5.6
Deep => BOOL
Attaches "Log::Trace" to all packages (that define a TRACE
function). Any TRACEF, DUMP and TRACE_HERE routines will also be
overridden in these packages.
Dumper => Data::Serializer backend
Specify a serialiser to be used for DUMPing data structures.
This should either be a string naming a Data::Serializer backend
(e.g. "YAML") or a hashref of parameters which will be passed to
Data::Serializer, e.g.
{
serializer => 'XML::Dumper',
options => {
dtd => 'path/to/my.dtd'
}
}
Note that the raw_serialise() method of Data::Serializer is used.
See Data::Serializer for more information.
If you do not have "Data::Serializer" installed, leave this option
undefined to use the "Data::Dumper" natively.
Default: undef (use standalone Data::Dumper)
Everywhere => BOOL
When used in conjunction with the "Deep" option, it will override
the standard behaviour of only enabling tracing in packages that
define "TRACE" stubs.
Default: false
Exclude => STRING|ARRAY
Exclude a module or list of modules from tracing.
Level => NUMBER|LIST|CODE
Specifies which trace levels to display.
If no "Level" is defined, all TRACE statements will be output.
If the value is numeric, only TRACEs that are at the specified
level or below will be output.
If the value is a list of numbers, only TRACEs that match the
specified levels are output.
The level may also be a code reference which is passed the package
name and the TRACE level. It mst return a true value if the TRACE
is to be output.
Default: undef
Match => REGEX
Exports trace functions to packages that match the supplied regular
expression. Can be used in conjunction with "Exclude". You can
also use "Match" as an exclusion method if you give it a negative
look-ahead.
For example:
Match => qr/^(?!Acme::)/ # will exclude every module beginning with Acme::
and
Match => qr/^Acme::/ # does the reverse
Default: '.' # everything
Verbose => 0|1|2
You can use this option to prepend extra information to each trace
message. The levels represent increasing levels of verbosity:
0: the default*, don't 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)
This setting has no effect on the "custom" or "log" targets.
* the log target uses 'Verbose' level 2
ENVIRONMENT NOTES
The AutoImport feature overrides "CORE::require()" 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.
In mod_perl or other persistent interpreter environments, different
applications could trample on each other's "TRACE" routines if they use
Deep (or Everywhere) option. For example application A could route all
the trace output from Package::Foo into "appA.log" and then application
B could import Log::Trace over the top, re-routing all the trace output
from Package::Foo to "appB.log" 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
"Log::Trace".
"Log::Trace" has not been tested in a multi-threaded application.
DEPENDENCIES
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)
RELATED MODULES
Log::TraceMessages
"Log::TraceMessages" is similar in design and purpose to
"Log::Trace". 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. "Log::Trace" also offers
control over the output with the trace levels and supports more
output targets.
Log::Agent
"Log::Agent" offers a procedural interface to logging. It strikes a
good balance between configurability and ease of use. It differs to
"Log::Trace" in a number of ways. "Log::Agent" has a concept of
channels and priorities, while "Log::Trace" only offers levels.
"Log::Trace" also supports tracing code execution path and the
"Deep" import option. "Log::Trace" trades a certain amount of
configurability for increased ease-of use.
Log::Log4Perl
A feature rich perl port of the popular "log4j" 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 "Log::Trace" you need only remember
up to 4 simple functions and a handful of configuration options.
SEE ALSO
Log::Trace::Manual - A guide to using Log::TraceVERSION
$Revision: 1.70 $ on $Date: 2005/11/01 11:32:59 $ by $Author: colinr $
AUTHOR
John Alden and Simon Flack with some additions by Piers Kent and Wayne
Myers <cpan _at_ bbc _dot_ co _dot_ uk>
COPYRIGHT
(c) BBC 2005. This program is free software; you can redistribute it
and/or modify it under the GNU GPL.
See the file COPYING in this distribution, or
http://www.gnu.org/licenses/gpl.txt
perl v5.14.0 2005-11-24 Log::Trace(3)
