| Log::Trace - provides a unified approach to tracing |
Log::Trace - 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 use
Log::Trace qw( E<lt> mode E<gt> ) 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).
TRACE(@args)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');
printf() equivalent of TRACE. Also accepts an optional hashref:
TRACEF('%d items', scalar @items);
TRACEF({ Level => 5 }, '$%1.2d', $value);
DUMP('colours', [qw(red green blue)]); # outputs via TRACE
my $dump = DUMP('colours', [qw(red green blue)]); # output returned
TRACE_HERE()
TRACE_HERE();
TRACE_HERE({Level => 99});
'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:
$filehandle. Defaults to STDOUT
if no file handle is specified.
warn()s to STDERR.
use Log::Trace file => $filename, {Verbose => 2};
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.
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.
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 TRACEd.
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
Log::Trace to all packages (that define a TRACE function). Any
TRACEF, DUMP and TRACE_HERE routines will also be overridden in these packages.
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 the Data::Serializer manpage
for more information.
If you do not have C<Data::Serializer> installed, leave this option undefined to use the C<Data::Dumper> natively.
Default: undef (use standalone Data::Dumper)
Deep option, it will override the
standard behaviour of only enabling tracing in packages that define TRACE
stubs.
Default: false
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
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
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
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.
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)
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 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.
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.
the Log::Trace::Manual manpage - 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) 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
| Log::Trace - provides a unified approach to tracing |