Provided by: liblog-trace-perl_1.070-5_all bug

NAME

       Log::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::Trace

VERSION

       $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