Provides a unified approach to tracing
# 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
A module to provide a unified approach to tracing. A script can \*(C`use Log::Trace qw( < mode > )\*(C' to set the behaviour of the \s-1TRACE\s0 function.
By default, the trace functions are exported to the calling package only. You can export the trace functions to other packages with the \*(C`Deep\*(C' option. See \*(L"\s-1OPTIONS\s0\*(R" for more information.
All exports are in uppercase (to minimise collisions with \*(L"real\*(R" functions).
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) 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'); \*(C`printf()\*(C' equivalent of \s-1TRACE\s0. Also accepts an optional hashref: TRACEF('%d items', scalar @items); TRACEF({ Level => 5 }, '$%1.2d', $value); Serialises each of @args, optionally prepended with $message. 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. DUMP('colours', [qw(red green blue)]); # outputs via TRACE my $dump = DUMP('colours', [qw(red green blue)]); # output returned
TRACEs the current position on the call stack (file, line number, subroutine name, subroutine args). TRACE_HERE(); TRACE_HERE({Level => 99});
Controls where \s-1TRACE\s0 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 \*(C`arg\*(C' are:
Prints trace messages to the supplied $filehandle. Defaults to \*(C`STDOUT\*(C' if no file handle is specified.
Prints trace messages via \*(C`warn()\*(C's to \*(C`STDERR\*(C'.
Appends trace messages to a string reference. Append trace messages to a file. If the file doesn't exist, it will be created. This is equivalent to: use Log::Trace file => $filename, {Verbose => 2}; Logs trace messages to syslog via \*(C`Sys::Syslog\*(C', if available. You should consult your syslog configuration before using this option. The default $priority is '\*(C`debug\*(C'', and the \*(C`ident\*(C' is set to \*(C`Log::Trace\*(C'. You can configure the \*(C`priority\*(C', but beyond that, you can implement your own syslogging via the \*(C`custom\*(C' trace target.
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 \*(C`\%params\*(C' are optional. These two statements are functionally the same: import Log::Trace print => {Level => undef}; import Log::Trace 'print'; See \*(L"\s-1OPTIONS\s0\*(R" for more information. Note: If you use the \*(C`custom\*(C' tracing option, you should be careful about supplying a subroutine named \*(C`TRACE\*(C'.
Attaches a \*(C`TRACE\*(C' 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 \*(C`Deep\*(C' and \*(C`Everywhere\*(C' options. Note: Anonymous subroutines and \*(C`AUTOLOAD\*(C' are not \*(C`TRACE\*(C'd.
By default, \*(C`Log::Trace\*(C' will only set up \*(C`TRACE\*(C' routines in modules that have already been loaded. This option overrides \*(C`require()\*(C' so that modules loaded after \*(C`Log::Trace\*(C' can automatically be set up for tracing. Note: This is an experimental feature. See the \s-1ENVIRONMENT\s0 \s-1NOTES\s0 for information about behaviour under different versions of perl. This option has no effect on perl < 5.6
Attaches \*(C`Log::Trace\*(C' 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.
Specify a serialiser to be used for DUMPing data structures. 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. { 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 \*(C`Data::Serializer\*(C' installed, leave this option undefined to use the \*(C`Data::Dumper\*(C' natively. Default: undef (use standalone Data::Dumper)
When used in conjunction with the \*(C`Deep\*(C' option, it will override the standard behaviour of only enabling tracing in packages that define \*(C`TRACE\*(C' stubs. Default: false
Exclude a module or list of modules from tracing.
Specifies which trace levels to display. If no \*(C`Level\*(C' is defined, all \s-1TRACE\s0 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 \s-1TRACE\s0 level. It mst return a true value if the \s-1TRACE\s0 is to be output. Default: undef
Exports trace functions to packages that match the supplied regular expression. Can be used in conjunction with \*(C`Exclude\*(C'. You can also use \*(C`Match\*(C' 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
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 \*(C`custom\*(C' or \*(C`log\*(C' targets. * the log target uses 'Verbose' level 2
The AutoImport feature overrides \*(C`CORE::require()\*(C' 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 \*(C`TRACE\*(C' 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 \*(C`Log::Trace\*(C'.
\*(C`Log::Trace\*(C' has not been tested in a multi-threaded application.
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)
\*(C`Log::TraceMessages\*(C' is similar in design and purpose to \*(C`Log::Trace\*(C'. 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. \*(C`Log::Trace\*(C' also offers control over the output with the trace levels and supports more output targets.
\*(C`Log::Agent\*(C' offers a procedural interface to logging. It strikes a good balance between configurability and ease of use. It differs to \*(C`Log::Trace\*(C' in a number of ways. \*(C`Log::Agent\*(C' has a concept of channels and priorities, while \*(C`Log::Trace\*(C' only offers levels. \*(C`Log::Trace\*(C' also supports tracing code execution path and the \*(C`Deep\*(C' import option. \*(C`Log::Trace\*(C' trades a certain amount of configurability for increased ease-of use.
A feature rich perl port of the popular \*(C`log4j\*(C' 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 \*(C`Log::Trace\*(C' you need only remember up to 4 simple functions and a handful of configuration options.
Log::Trace::Manual - A guide to using Log::Trace
$Revision: 1.70 $ on $Date: 2005/11/01 11:32:59 $ by $Author: colinr $
John Alden and Simon Flack with some additions by Piers Kent and Wayne Myers <cpan _at_ bbc _dot_ co _dot_ uk>
(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.
See the file \s-1COPYING\s0 in this distribution, or http://www.gnu.org/licenses/gpl.txt