NAME¶

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¶

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:

        import Log::Trace print => {Level => undef};
        import Log::Trace 'print';

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¶

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¶

VERSION¶

AUTHOR¶

COPYRIGHT¶