1Log::Trace(3)         User Contributed Perl Documentation        Log::Trace(3)
2
3
4

NAME

6       Log::Trace - provides a unified approach to tracing
7

SYNOPSIS

9               # The tracing targets
10               use Log::Trace; # No output
11               use Log::Trace 'print'; # print to STDOUT
12               use Log::Trace log => '/var/log/foo.log'; # Output to log file
13               use Log::Trace print => { Level => 3 };
14
15               # Switch on/off logging with a constant
16               use Log::Trace;
17               import Log::Trace ('log' => LOGFILE) if TRACING;
18
19
20               # Set up tracing for all packages that advertise TRACE
21               use Foo;
22               use Bar;
23               use Log::Trace warn => { Deep => 1 };
24
25               # Sets up tracing in all subpackages excluding Foo
26               use Log::Trace warn => {Deep => 1, 'Exclude' => 'Foo'};
27
28
29               # Exported functions
30               TRACE("Record this...");
31               TRACE({Level => 2}, "Only shown if tracing level is 2 or higher");
32               TRACEF("A la printf: %d-%.2f", 1, 2.9999);
33               TRACE_HERE();           # Record where we are (file, line, sub, args)
34               DUMP(\@loh, \%hoh);     # Trace out via Data::Dumper
35               DUMP("Title", \@loh);   # Trace out via Data::Dumper
36               my $dump = DUMP(@args); # Dump is returned without being traced
37

DESCRIPTION

39       A module to provide a unified approach to tracing. A script can "use
40       Log::Trace qw( < mode > )" to set the behaviour of the TRACE function.
41
42       By default, the trace functions are exported to the calling package
43       only. You can export the trace functions to other packages with the
44       "Deep" option. See "OPTIONS" for more information.
45
46       All exports are in uppercase (to minimise collisions with "real"
47       functions).
48

FUNCTIONS

50       TRACE(@args)
51           Output a message. Where the message actually goes depends on how
52           you imported Log::Trace (See "enabling Log::Trace"" in "Importing)
53
54           The first argument is an optional hashref of options:
55
56                   TRACE('A simple message');
57
58           vs:
59
60                   TRACE({ Level => 2.1 }, 'A message at a specified trace level');
61
62       TRACEF($format, @args)
63           "printf()" equivalent of TRACE. Also accepts an optional hashref:
64
65                   TRACEF('%d items', scalar @items);
66                   TRACEF({ Level => 5 }, '$%1.2d', $value);
67
68       DUMP([$message,] @args)
69           Serialises each of @args, optionally prepended with $message. If
70           called in a non-void context, DUMP will return the serialised data
71           rather than TRACE it. This is useful if you want to DUMP a
72           datastructure at a specific tracing level.
73
74                   DUMP('colours', [qw(red green blue)]);             # outputs via TRACE
75                   my $dump = DUMP('colours', [qw(red green blue)]);  # output returned
76
77       TRACE_HERE()
78           TRACEs the current position on the call stack (file, line number,
79           subroutine name, subroutine args).
80
81                   TRACE_HERE();
82                   TRACE_HERE({Level => 99});
83

Importing/enabling Log::Trace

85       import($target, [$arg], [\%params])
86           Controls where TRACE messages go. This method is called
87           automatically when you call 'use Log::Trace;', but you may
88           explicitly call this method at runtime. Compare the following:
89
90                   use Log::Trace 'print';
91
92           which is the same as
93
94                   BEGIN {
95                           require Log::Trace;
96                           Log::Trace->import('print');
97                   }
98
99           Valid combinations of $target and "arg" are:
100
101           print => $filehandle
102               Prints trace messages to the supplied $filehandle. Defaults to
103               "STDOUT" if no file handle is specified.
104
105           warn
106               Prints trace messages via "warn()"s to "STDERR".
107
108           buffer => \$buffer
109               Appends trace messages to a string reference.
110
111           file => $filename
112               Append trace messages to a file. If the file doesn't exist, it
113               will be created.
114
115           log => $filename
116               This is equivalent to:
117
118                       use Log::Trace file => $filename, {Verbose => 2};
119
120           syslog => $priority
121               Logs trace messages to syslog via "Sys::Syslog", if available.
122
123               You should consult your syslog configuration before using this
124               option.
125
126               The default $priority is '"debug"', and the "ident" is set to
127               "Log::Trace". You can configure the "priority", but beyond
128               that, you can implement your own syslogging via the "custom"
129               trace target.
130
131           custom => \&custom_trace_sub
132               Trace messages are processed by a custom subroutine. E.g.
133
134                       use Log::Trace custom => \&mylogger;
135
136                       sub mylogger {
137                               my @messages = @_;
138                               foreach (@messages) {
139                                       # highly sensitive trace messages!
140                                       tr/a-zA-Z/n-za-mN-ZA-M/;
141                                       print;
142                               }
143                       }
144
145           The import "\%params" are optional. These two statements are
146           functionally the same:
147
148                   import Log::Trace print => {Level => undef};
149                   import Log::Trace 'print';
150
151           See "OPTIONS" for more information.
152
153           Note: If you use the "custom" tracing option, you should be careful
154           about supplying a subroutine named "TRACE".
155

OPTIONS

157       AllSubs => BOOL
158           Attaches a "TRACE" statement to all subroutines in the package.
159           This can be used to track the execution path of your code. It is
160           particularly useful when used in conjunction with "Deep" and
161           "Everywhere" options.
162
163           Note: Anonymous subroutines and "AUTOLOAD" are not "TRACE"d.
164
165       AutoImport => BOOL
166           By default, "Log::Trace" will only set up "TRACE" routines in
167           modules that have already been loaded. This option overrides
168           "require()" so that modules loaded after "Log::Trace" can
169           automatically be set up for tracing.
170
171           Note: This is an experimental feature. See the ENVIRONMENT NOTES
172           for information about behaviour under different versions of perl.
173
174           This option has no effect on perl < 5.6
175
176       Deep => BOOL
177           Attaches "Log::Trace" to all packages (that define a TRACE
178           function). Any TRACEF, DUMP and TRACE_HERE routines will also be
179           overridden in these packages.
180
181       Dumper => Data::Serializer backend
182           Specify a serialiser to be used for DUMPing data structures.
183
184           This should either be a string naming a Data::Serializer backend
185           (e.g. "YAML") or a hashref of parameters which will be passed to
186           Data::Serializer, e.g.
187
188                   {
189                           serializer => 'XML::Dumper',
190                           options => {
191                                   dtd => 'path/to/my.dtd'
192                           }
193                   }
194
195           Note that the raw_serialise() method of Data::Serializer is used.
196           See Data::Serializer for more information.
197
198           If you do not have "Data::Serializer" installed, leave this option
199           undefined to use the "Data::Dumper" natively.
200
201           Default: undef (use standalone Data::Dumper)
202
203       Everywhere => BOOL
204           When used in conjunction with the "Deep" option, it will override
205           the standard behaviour of only enabling tracing in packages that
206           define "TRACE" stubs.
207
208           Default: false
209
210       Exclude => STRING|ARRAY
211           Exclude a module or list of modules from tracing.
212
213       Level => NUMBER|LIST|CODE
214           Specifies which trace levels to display.
215
216           If no "Level" is defined, all TRACE statements will be output.
217
218           If the value is numeric, only TRACEs that are at the specified
219           level or below will be output.
220
221           If the value is a list of numbers, only TRACEs that match the
222           specified levels are output.
223
224           The level may also be a code reference which is passed the package
225           name and the TRACE level. It mst return a true value if the TRACE
226           is to be output.
227
228           Default: undef
229
230       Match => REGEX
231           Exports trace functions to packages that match the supplied regular
232           expression. Can be used in conjunction with  "Exclude". You can
233           also use "Match" as an exclusion method if you give it a negative
234           look-ahead.
235
236           For example:
237
238                   Match => qr/^(?!Acme::)/  # will exclude every module beginning with Acme::
239
240           and
241
242                   Match => qr/^Acme::/      # does the reverse
243
244           Default: '.' # everything
245
246       Verbose => 0|1|2
247           You can use this option to prepend extra information to each trace
248           message. The levels represent increasing levels of verbosity:
249
250                   0: the default*, don't add anything
251                   1: adds subroutine name and line number to the trace output
252                   2: As [1], plus a filename and timestamp (in ISO 8601 : 2000 format)
253
254           This setting has no effect on the "custom" or "log" targets.
255
256           * the log target uses 'Verbose' level 2
257

ENVIRONMENT NOTES

259       The AutoImport feature overrides "CORE::require()" which requires perl
260       5.6, but you may see unexpected errors if you aren't using at least
261       perl 5.8. The AutoImport option has no effect on perl < 5.6.
262
263       In mod_perl or other persistent interpreter environments, different
264       applications could trample on each other's "TRACE" routines if they use
265       Deep (or Everywhere) option.  For example application A could route all
266       the trace output from Package::Foo into "appA.log" and then application
267       B could import Log::Trace over the top, re-routing all the trace output
268       from Package::Foo to "appB.log" for evermore.  One way around this is
269       to ensure you always import Log::Trace on every run in a persistent
270       environment from all your applications that use the Deep option.  We
271       may provide some more tools to work around this in a later version of
272       "Log::Trace".
273
274       "Log::Trace" has not been tested in a multi-threaded application.
275

DEPENDENCIES

277               Carp
278               Time::HiRes      (used if available)
279               Data::Dumper     (used if available - necessary for meaningful DUMP output)
280               Data::Serializer (optional - to customise DUMP output)
281               Sys::Syslog      (loaded on demand)
282
284       Log::TraceMessages
285           "Log::TraceMessages" is similar in design and purpose to
286           "Log::Trace".  However, it only offers a subset of this module's
287           functionality. Most notably, it doesn't offer a mechanism to
288           control the tracing output of an entire application - tracing must
289           be enabled on a module-by-module basis. "Log::Trace" also offers
290           control over the output with the trace levels and supports more
291           output targets.
292
293       Log::Agent
294           "Log::Agent" offers a procedural interface to logging. It strikes a
295           good balance between configurability and ease of use. It differs to
296           "Log::Trace" in a number of ways. "Log::Agent" has a concept of
297           channels and priorities, while "Log::Trace" only offers levels.
298           "Log::Trace" also supports tracing code execution path and the
299           "Deep" import option. "Log::Trace" trades a certain amount of
300           configurability for increased ease-of use.
301
302       Log::Log4Perl
303           A feature rich perl port of the popular "log4j" library for Java.
304           It is object-oriented and comprised of more than 30 modules. It has
305           an impressive feature set, but some people may be frightened of its
306           complexity. In contrast, to use "Log::Trace" you need only remember
307           up to 4 simple functions and a handful of configuration options.
308

SEE ALSO

310       Log::Trace::Manual - A guide to using Log::Trace
311

VERSION

313       $Revision: 1.70 $ on $Date: 2005/11/01 11:32:59 $ by $Author: colinr $
314

AUTHOR

316       John Alden and Simon Flack with some additions by Piers Kent and Wayne
317       Myers <cpan _at_ bbc _dot_ co _dot_ uk>
318
320       (c) BBC 2005. This program is free software; you can redistribute it
321       and/or modify it under the GNU GPL.
322
323       See the file COPYING in this distribution, or
324       http://www.gnu.org/licenses/gpl.txt
325
326
327
328perl v5.28.1                      2005-11-24                     Log::Trace(3)
Impressum