Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
Log::Trace(3)	      User Contributed Perl Documentation	 Log::Trace(3)

       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( <	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"

	   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');


		   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

	   TRACEs the current position on the call stack (file,	line number,
	   subroutine name, subroutine args).

		   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;

	   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.

	       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

	       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!

	   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".

       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

	   For example:

		   Match => qr/^(?!Acme::)/  # will exclude every module beginning with	Acme::


		   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

       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" has	not been tested	in a multi-threaded application.

	       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.

	   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.

       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) 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

perl v5.32.0			  2005-11-24			 Log::Trace(3)


Want to link to this manual page? Use this URL:

home | help