--- name: "Log::Trace" section: "3pm" platform: "linux" package: "liblog-trace-perl" version: "1.070-5" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/Log::Trace" --- # Log::Trace(3pm) provides a unified approach to tracing ## 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 \ ## 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