1Log::Any(3) User Contributed Perl Documentation Log::Any(3)
2
6 Log::Any - Bringing loggers and listeners together
7
9 version 1.708
10
12 In a CPAN or other module:
13 package Foo;
15 use Log::Any qw($log);
16 # log a string
18 $log->error("an error occurred");
19 # log a string and some data
21 $log->info("program started",
22 {progname => $0, pid => $$, perl_version => $]});
23 # log a string and data using a format string
25 $log->debugf("arguments are: %s", \@_);
26 # log an error and throw an exception
28 die $log->fatal("a fatal error occurred");
29 In a Moo/Moose-based module:
31 package Foo;
33 use Log::Any ();
34 use Moo;
35 has log => (
37 is => 'ro',
38 default => sub { Log::Any->get_logger },
39 );
40 In your application:
42 use Foo;
44 use Log::Any::Adapter;
45 # Send all logs to Log::Log4perl
47 Log::Any::Adapter->set('Log4perl');
48 # Send all logs to Log::Dispatch
50 my $log = Log::Dispatch->new(outputs => [[ ... ]]);
51 Log::Any::Adapter->set( 'Dispatch', dispatcher => $log );
52 # See Log::Any::Adapter documentation for more options
54
56 "Log::Any" provides a standard log production API for modules.
57 Log::Any::Adapter allows applications to choose the mechanism for log
58 consumption, whether screen, file or another logging mechanism like
59 Log::Dispatch or Log::Log4perl.
60 Many modules have something interesting to say. Unfortunately there is
62 no standard way for them to say it - some output to STDERR, others to
63 "warn", others to custom file logs. And there is no standard way to get
64 a module to start talking - sometimes you must call a uniquely named
65 method, other times set a package variable.
66 This being Perl, there are many logging mechanisms available on CPAN.
68 Each has their pros and cons. Unfortunately, the existence of so many
69 mechanisms makes it difficult for a CPAN author to commit his/her users
70 to one of them. This may be why many CPAN modules invent their own
71 logging or choose not to log at all.
72 To untangle this situation, we must separate the two parts of a logging
74 API. The first, log production, includes methods to output logs (like
75 "$log->debug") and methods to inspect whether a log level is activated
76 (like "$log->is_debug"). This is generally all that CPAN modules care
77 about. The second, log consumption, includes a way to configure where
78 logging goes (a file, the screen, etc.) and the code to send it there.
79 This choice generally belongs to the application.
80 A CPAN module uses "Log::Any" to get a log producer object. An
82 application, in turn, may choose one or more logging mechanisms via
83 Log::Any::Adapter, or none at all.
84 "Log::Any" has a very tiny footprint and no dependencies beyond Perl
86 5.8.1, which makes it appropriate for even small CPAN modules to use.
87 It defaults to 'null' logging activity, so a module can safely log
88 without worrying about whether the application has chosen (or will ever
89 choose) a logging mechanism.
90 See <http://www.openswartz.com/2007/09/06/standard-logging-api/> for
92 the original post proposing this module.
93
95 "Log::Any" supports the following log levels and aliases, which is
96 meant to be inclusive of the major logging packages:
97 trace
99 debug
100 info (inform)
101 notice
102 warning (warn)
103 error (err)
104 critical (crit, fatal)
105 alert
106 emergency
107 Levels are translated as appropriate to the underlying logging
109 mechanism. For example, log4perl only has six levels, so we translate
110 'notice' to 'info' and the top three levels to 'fatal'. See the
111 documentation of an adapter class for specifics.
112
114 Every logger has a category, generally the name of the class that asked
115 for the logger. Some logging mechanisms, like log4perl, can direct logs
116 to different places depending on category.
117
119 Getting a logger
120 The most convenient way to get a logger in your module is:
121 use Log::Any qw($log);
123 This creates a package variable $log and assigns it to the logger for
125 the current package. It is equivalent to
126 our $log = Log::Any->get_logger;
128 In general, to get a logger for a specified category:
130 my $log = Log::Any->get_logger(category => $category)
132 If no category is specified, the calling package is used.
134 A logger object is an instance of Log::Any::Proxy, which passes on
136 messages to the Log::Any::Adapter handling its category.
137 If the "proxy_class" argument is passed, an alternative to
139 Log::Any::Proxy (such as a subclass) will be instantiated and returned
140 instead. The argument is automatically prepended with
141 "Log::Any::Proxy::". If instead you want to pass the full name of a
142 proxy class, prefix it with a "+". E.g.
143 # Log::Any::Proxy::Foo
145 my $log = Log::Any->get_logger(proxy_class => 'Foo');
146 # MyLog::Proxy
148 my $log = Log::Any->get_logger(proxy_class => '+MyLog::Proxy');
149 Logging
151 To log a message, pass a single string to any of the log levels or
152 aliases. e.g.
153 $log->error("this is an error");
155 $log->warn("this is a warning");
156 $log->warning("this is also a warning");
157 The log string will be returned so that it can be used further (e.g.
159 for a "die" or "warn" call).
160 You should not include a newline in your message; that is the
162 responsibility of the logging mechanism, which may or may not want the
163 newline.
164 If you want to log additional structured data alongside with your
166 string, you can add a single hashref after your log string. e.g.
167 $log->info("program started",
169 {progname => $0, pid => $$, perl_version => $]});
170 If the configured Log::Any::Adapter does not support logging structured
172 data, the hash will be converted to a string using Data::Dumper.
173 There are also versions of each of the logging methods with an
175 additional "f" suffix ("infof", "errorf", "debugf", etc.) that format a
176 list of arguments. The specific formatting mechanism and meaning of
177 the arguments is controlled by the Log::Any::Proxy object.
178 $log->errorf("an error occurred: %s", $@);
180 $log->debugf("called with %d params: %s", $param_count, \@params);
181 By default it renders like "sprintf", with the following additional
183 features:
184 • Any complex references (like "\@params" above) are automatically
186 converted to single-line strings with Data::Dumper.
187 • Any undefined values are automatically converted to the string
189 "<undef>".
190 Log level detection
192 To detect whether a log level is on, use "is_" followed by any of the
193 log levels or aliases. e.g.
194 if ($log->is_info()) { ... }
196 $log->debug("arguments are: " . Dumper(\@_))
197 if $log->is_debug();
198 This is important for efficiency, as you can avoid the work of putting
200 together the logging message (in the above case, stringifying @_) if
201 the log level is not active.
202 The formatting methods ("infof", "errorf", etc.) check the log level
204 for you.
205 Some logging mechanisms don't support detection of log levels. In these
207 cases the detection methods will always return 1.
208 In contrast, the default logging mechanism - Null - will return 0 for
210 all detection methods.
211 Log context data
213 "Log::Any" supports logging context data by exposing the "context"
214 hashref. All the key/value pairs added to this hash will be printed
215 with every log message. You can localize the data so that it will be
216 removed again automatically at the end of the block:
217 $log->context->{directory} = $dir;
219 for my $file (glob "$dir/*") {
220 local $log->context->{file} = basename($file);
221 $log->warn("Can't read file!") unless -r $file;
222 }
223 This will produce the following line:
225 Can't read file! {directory => '/foo',file => 'bar'}
227 If the configured Log::Any::Adapter does not support structured data,
229 the context hash will be converted to a string using Data::Dumper, and
230 will be appended to the log message.
231 Setting an alternate default logger
233 When no other adapters are configured for your logger, "Log::Any" uses
234 the "default_adapter". To choose something other than Null as the
235 default, either set the "LOG_ANY_DEFAULT_ADAPTER" environment variable,
236 or pass it as a parameter when loading "Log::Any"
237 use Log::Any '$log', default_adapter => 'Stderr';
239 The name of the default class follows the same rules as used by
241 Log::Any::Adapter.
242 To pass arguments to the default adapter's constructor, use an
244 arrayref:
245 use Log::Any '$log', default_adapter => [ 'File' => '/var/log/mylog.log' ];
247 When a consumer configures their own adapter, the default adapter will
249 be overridden. If they later remove their adapter, the default adapter
250 will be used again.
251 Configuring the proxy
253 Any parameters passed on the import line or via the "get_logger" method
254 are passed on to the Log::Any::Proxy constructor.
255 use Log::Any '$log', filter => \&myfilter;
257 Testing
259 Log::Any::Test provides a mechanism to test code that uses "Log::Any".
260
262 Log::Any provides modules with a Log::Any::Proxy object, which is the
263 log producer. To consume its output and direct it where you want (a
264 file, the screen, syslog, etc.), you use Log::Any::Adapter along with a
265 destination-specific subclass.
266 For example, to send output to a file via Log::Any::Adapter::File, your
268 application could do this:
269 use Log::Any::Adapter ('File', '/path/to/file.log');
271 See the Log::Any::Adapter documentation for more details.
273
275 Isn't Log::Any just yet another logging mechanism?
276 No. "Log::Any" does not include code that knows how to log to a
277 particular place (file, screen, etc.) It can only forward logging
278 requests to another logging mechanism.
279 Why don't you just pick the best logging mechanism, and use and promote
281 it?
282 Each of the logging mechanisms have their pros and cons,
283 particularly in terms of how they are configured. For example,
284 log4perl offers a great deal of power and flexibility but uses a
285 global and potentially heavy configuration, whereas Log::Dispatch
286 is extremely configuration-light but doesn't handle categories.
287 There is also the unnamed future logger that may have advantages
288 over either of these two, and all the custom in-house loggers
289 people have created and cannot (for whatever reason) stop using.
290 Is it safe for my critical module to depend on Log::Any?
292 Our intent is to keep "Log::Any" minimal, and change it only when
293 absolutely necessary. Most of the "innovation", if any, is expected
294 to occur in "Log::Any::Adapter", which your module should not have
295 to depend on (unless it wants to direct logs somewhere specific).
296 "Log::Any" has no non-core dependencies.
297 Why doesn't Log::Any use insert modern Perl technique?
299 To encourage CPAN module authors to adopt and use "Log::Any", we
300 aim to have as few dependencies and chances of breakage as
301 possible. Thus, no "Moose" or other niceties.
302
304 • Jonathan Swartz <swartz@pobox.com>
305 • David Golden <dagolden@cpan.org>
307 • Doug Bell <preaction@cpan.org>
309 • Daniel Pittman <daniel@rimspace.net>
311 • Stephen Thirlwall <sdt@cpan.org>
313
315 • bj5004 <bartosz.jakubski@hurra.com>
316 • cm-perl <cm-perl@users.noreply.github.com>
318 • Jonathan <jjrs.pam+github@gmail.com>
320 • Karen Etheridge <ether@cpan.org>
322 • Konstantin S. Uvarin <khedin@gmail.com>
324 • Lucas Kanashiro <kanashiro.duarte@gmail.com>
326 • Maros Kollar <maros.kollar@geizhals.at>
328 • Maxim Vuets <maxim.vuets@booking.com>
330 • mephinet <mephinet@gmx.net>
332 • Michael Conrad <mconrad@intellitree.com>
334 • Nick Tonkin <1nickt@users.noreply.github.com>
336 • Paul Durden <alabamapaul@gmail.com>
338 • Philipp Gortan <philipp.gortan@apa.at>
340 • Phill Legault <saladdayllc@gmail.com>
342 • Shlomi Fish <shlomif@shlomifish.org>
344
346 This software is copyright (c) 2017 by Jonathan Swartz, David Golden,
347 and Doug Bell.
348 This is free software; you can redistribute it and/or modify it under
350 the same terms as the Perl 5 programming language system itself.
351perl v5.32.1 2021-01-27 Log::Any(3)