1Log::Trace(3) User Contributed Perl Documentation Log::Trace(3)
2
6 Log::Trace - provides a unified approach to tracing
7
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 # Switch on/off logging with a constant
16 use Log::Trace;
17 import Log::Trace ('log' => LOGFILE) if TRACING;
18 # Set up tracing for all packages that advertise TRACE
21 use Foo;
22 use Bar;
23 use Log::Trace warn => { Deep => 1 };
24 # Sets up tracing in all subpackages excluding Foo
26 use Log::Trace warn => {Deep => 1, 'Exclude' => 'Foo'};
27 # 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
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 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 All exports are in uppercase (to minimise collisions with "real"
47 functions).
48
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 The first argument is an optional hashref of options:
55 TRACE('A simple message');
57 vs:
59 TRACE({ Level => 2.1 }, 'A message at a specified trace level');
61 TRACEF($format, @args)
63 printf() equivalent of TRACE. Also accepts an optional hashref:
64 TRACEF('%d items', scalar @items);
66 TRACEF({ Level => 5 }, '$%1.2d', $value);
67 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 DUMP('colours', [qw(red green blue)]); # outputs via TRACE
75 my $dump = DUMP('colours', [qw(red green blue)]); # output returned
76 TRACE_HERE()
78 TRACEs the current position on the call stack (file, line number,
79 subroutine name, subroutine args).
80 TRACE_HERE();
82 TRACE_HERE({Level => 99});
83
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 use Log::Trace 'print';
91 which is the same as
93 BEGIN {
95 require Log::Trace;
96 Log::Trace->import('print');
97 }
98 Valid combinations of $target and "arg" are:
100 print => $filehandle
102 Prints trace messages to the supplied $filehandle. Defaults to
103 "STDOUT" if no file handle is specified.
104 warn
106 Prints trace messages via warn()s to "STDERR".
107 buffer => \$buffer
109 Appends trace messages to a string reference.
110 file => $filename
112 Append trace messages to a file. If the file doesn't exist, it
113 will be created.
114 log => $filename
116 This is equivalent to:
117 use Log::Trace file => $filename, {Verbose => 2};
119 syslog => $priority
121 Logs trace messages to syslog via "Sys::Syslog", if available.
122 You should consult your syslog configuration before using this
124 option.
125 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 custom => \&custom_trace_sub
132 Trace messages are processed by a custom subroutine. E.g.
133 use Log::Trace custom => \&mylogger;
135 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 The import "\%params" are optional. These two statements are
146 functionally the same:
147 import Log::Trace print => {Level => undef};
149 import Log::Trace 'print';
150 See "OPTIONS" for more information.
152 Note: If you use the "custom" tracing option, you should be careful
154 about supplying a subroutine named "TRACE".
155
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 Note: Anonymous subroutines and "AUTOLOAD" are not "TRACE"d.
164 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 Note: This is an experimental feature. See the ENVIRONMENT NOTES
172 for information about behaviour under different versions of perl.
173 This option has no effect on perl < 5.6
175 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 Dumper => Data::Serializer backend
182 Specify a serialiser to be used for DUMPing data structures.
183 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 {
189 serializer => 'XML::Dumper',
190 options => {
191 dtd => 'path/to/my.dtd'
192 }
193 }
194 Note that the raw_serialise() method of Data::Serializer is used.
196 See Data::Serializer for more information.
197 If you do not have "Data::Serializer" installed, leave this option
199 undefined to use the "Data::Dumper" natively.
200 Default: undef (use standalone Data::Dumper)
202 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 Default: false
209 Exclude => STRING|ARRAY
211 Exclude a module or list of modules from tracing.
212 Level => NUMBER|LIST|CODE
214 Specifies which trace levels to display.
215 If no "Level" is defined, all TRACE statements will be output.
217 If the value is numeric, only TRACEs that are at the specified
219 level or below will be output.
220 If the value is a list of numbers, only TRACEs that match the
222 specified levels are output.
223 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 Default: undef
229 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 For example:
237 Match => qr/^(?!Acme::)/ # will exclude every module beginning with Acme::
239 and
241 Match => qr/^Acme::/ # does the reverse
243 Default: '.' # everything
245 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 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 This setting has no effect on the "custom" or "log" targets.
255 * the log target uses 'Verbose' level 2
257
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 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 "Log::Trace" has not been tested in a multi-threaded application.
275
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 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 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
310 Log::Trace::Manual - A guide to using Log::Trace
311
313 $Revision: 1.70 $ on $Date: 2005/11/01 11:32:59 $ by $Author: colinr $
314
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 See the file COPYING in this distribution, or
324 http://www.gnu.org/licenses/gpl.txt
325perl v5.38.0 2023-07-20 Log::Trace(3)