1AnyEvent::Log(3) User Contributed Perl Documentation AnyEvent::Log(3)
2
6 AnyEvent::Log - simple logging "framework"
7
9 Simple uses:
10 use AnyEvent;
12 AE::log fatal => "No config found, cannot continue!"; # never returns
14 AE::log alert => "The battery died!";
15 AE::log crit => "The battery temperature is too hot!";
16 AE::log error => "Division by zero attempted.";
17 AE::log warn => "Couldn't delete the file.";
18 AE::log note => "Wanted to create config, but config already exists.";
19 AE::log info => "File soandso successfully deleted.";
20 AE::log debug => "the function returned 3";
21 AE::log trace => "going to call function abc";
22 Log level overview:
24 LVL NAME SYSLOG PERL NOTE
26 1 fatal emerg exit system unusable, aborts program!
27 2 alert failure in primary system
28 3 critical crit failure in backup system
29 4 error err die non-urgent program errors, a bug
30 5 warn warning possible problem, not necessarily error
31 6 note notice unusual conditions
32 7 info normal messages, no action required
33 8 debug debugging messages for development
34 9 trace copious tracing output
35 "Complex" uses (for speed sensitive code, e.g. trace/debug messages):
37 use AnyEvent::Log;
39 my $tracer = AnyEvent::Log::logger trace => \$my $trace;
41 $tracer->("i am here") if $trace;
43 $tracer->(sub { "lots of data: " . Dumper $self }) if $trace;
44 Configuration (also look at the EXAMPLES section):
46 # set logging for the current package to errors and higher only
48 AnyEvent::Log::ctx->level ("error");
49 # set logging level to suppress anything below "notice"
51 $AnyEvent::Log::FILTER->level ("notice");
52 # send all critical and higher priority messages to syslog,
54 # regardless of (most) other settings
55 $AnyEvent::Log::COLLECT->attach (new AnyEvent::Log::Ctx
56 level => "critical",
57 log_to_syslog => "user",
58 );
59
61 This module implements a relatively simple "logging framework". It
62 doesn't attempt to be "the" logging solution or even "a" logging
63 solution for AnyEvent - AnyEvent simply creates logging messages
64 internally, and this module more or less exposes the mechanism, with
65 some extra spiff to allow using it from other modules as well.
66 Remember that the default verbosity level is 4 ("error"), so only
68 errors and more important messages will be logged, unless you set
69 "PERL_ANYEVENT_VERBOSE" to a higher number before starting your program
70 ("AE_VERBOSE=5" is recommended during development), or change the
71 logging level at runtime with something like:
72 use AnyEvent::Log;
74 $AnyEvent::Log::FILTER->level ("info");
75 The design goal behind this module was to keep it simple (and small),
77 but make it powerful enough to be potentially useful for any module,
78 and extensive enough for the most common tasks, such as logging to
79 multiple targets, or being able to log into a database.
80 The module is also usable before AnyEvent itself is initialised, in
82 which case some of the functionality might be reduced.
83 The amount of documentation might indicate otherwise, but the runtime
85 part of the module is still just below 300 lines of code.
86
88 Logging levels in this module range from 1 (highest priority) to 9
89 (lowest priority). Note that the lowest numerical value is the highest
90 priority, so when this document says "higher priority" it means "lower
91 numerical value".
92 Instead of specifying levels by name you can also specify them by
94 aliases:
95 LVL NAME SYSLOG PERL NOTE
97 1 fatal emerg exit system unusable, aborts program!
98 2 alert failure in primary system
99 3 critical crit failure in backup system
100 4 error err die non-urgent program errors, a bug
101 5 warn warning possible problem, not necessarily error
102 6 note notice unusual conditions
103 7 info normal messages, no action required
104 8 debug debugging messages for development
105 9 trace copious tracing output
106 As you can see, some logging levels have multiple aliases - the first
108 one is the "official" name, the second one the "syslog" name (if it
109 differs) and the third one the "perl" name, suggesting (only!) that you
110 log "die" messages at "error" priority. The NOTE column tries to
111 provide some rationale on how to chose a logging level.
112 As a rough guideline, levels 1..3 are primarily meant for users of the
114 program (admins, staff), and are the only ones logged to STDERR by
115 default. Levels 4..6 are meant for users and developers alike, while
116 levels 7..9 are usually meant for developers.
117 You can normally only log a message once at highest priority level (1,
119 "fatal"), because logging a fatal message will also quit the program -
120 so use it sparingly :)
121 For example, a program that finds an unknown switch on the commandline
123 might well use a fatal logging level to tell users about it - the
124 "system" in this case would be the program, or module.
125 Some methods also offer some extra levels, such as 0, "off", "none" or
127 "all" - these are only valid for the methods that documented them.
128
130 The following functions allow you to log messages. They always use the
131 caller's package as a "logging context". Also, the main logging
132 function, "log", is aliased to "AnyEvent::log" and "AE::log" when the
133 "AnyEvent" module is loaded.
134 AnyEvent::Log::log $level, $msg[, @args]
136 Requests logging of the given $msg with the given log level, and
137 returns true if the message was logged somewhere.
138 For loglevel "fatal", the program will abort.
140 If only a $msg is given, it is logged as-is. With extra @args, the
142 $msg is interpreted as an sprintf format string.
143 The $msg should not end with "\n", but may if that is convenient
145 for you. Also, multiline messages are handled properly.
146 Last not least, $msg might be a code reference, in which case it is
148 supposed to return the message. It will be called only then the
149 message actually gets logged, which is useful if it is costly to
150 create the message in the first place.
151 This function takes care of saving and restoring $! and $@, so you
153 don't have to.
154 Whether the given message will be logged depends on the maximum log
156 level and the caller's package. The return value can be used to
157 ensure that messages or not "lost" - for example, when
158 AnyEvent::Debug detects a runtime error it tries to log it at "die"
159 level, but if that message is lost it simply uses warn.
160 Note that you can (and should) call this function as
162 "AnyEvent::log" or "AE::log", without "use"-ing this module if
163 possible (i.e. you don't need any additional functionality), as
164 those functions will load the logging module on demand only. They
165 are also much shorter to write.
166 Also, if you optionally generate a lot of debug messages (such as
168 when tracing some code), you should look into using a logger
169 callback and a boolean enabler (see "logger", below).
170 Example: log something at error level.
172 AE::log error => "something";
174 Example: use printf-formatting.
176 AE::log info => "%5d %-10.10s %s", $index, $category, $msg;
178 Example: only generate a costly dump when the message is actually
180 being logged.
181 AE::log debug => sub { require Data::Dump; Data::Dump::dump \%cache };
183 $logger = AnyEvent::Log::logger $level[, \$enabled]
185 Creates a code reference that, when called, acts as if the
186 "AnyEvent::Log::log" function was called at this point with the
187 given level. $logger is passed a $msg and optional @args, just as
188 with the "AnyEvent::Log::log" function:
189 my $debug_log = AnyEvent::Log::logger "debug";
191 $debug_log->("debug here");
193 $debug_log->("%06d emails processed", 12345);
194 $debug_log->(sub { $obj->as_string });
195 The idea behind this function is to decide whether to log before
197 actually logging - when the "logger" function is called once, but
198 the returned logger callback often, then this can be a tremendous
199 speed win.
200 Despite this speed advantage, changes in logging configuration will
202 still be reflected by the logger callback, even if configuration
203 changes after it was created.
204 To further speed up logging, you can bind a scalar variable to the
206 logger, which contains true if the logger should be called or not -
207 if it is false, calling the logger can be safely skipped. This
208 variable will be updated as long as $logger is alive.
209 Full example:
211 # near the init section
213 use AnyEvent::Log;
214 my $debug_log = AnyEvent:Log::logger debug => \my $debug;
216 # and later in your program
218 $debug_log->("yo, stuff here") if $debug;
219 $debug and $debug_log->("123");
221 AnyEvent::Log::exact_time $on
223 By default, "AnyEvent::Log" will use "AE::now", i.e. the cached
224 eventloop time, for the log timestamps. After calling this function
225 with a true value it will instead resort to "AE::time", i.e. fetch
226 the current time on each log message. This only makes a difference
227 for event loops that actually cache the time (such as EV or
228 AnyEvent::Loop).
229 This setting can be changed at any time by calling this function.
231 Since "AnyEvent::Log" has to work even before the AnyEvent has been
233 initialised, this switch will also decide whether to use
234 "CORE::time" or "Time::HiRes::time" when logging a message before
235 AnyEvent becomes available.
236 AnyEvent::Log::format_time $timestamp
238 Formats a timestamp as returned by "AnyEvent->now" or
239 "AnyEvent->time" or many other functions in the same way as
240 "AnyEvent::Log" does.
241 In your main program (as opposed to in your module) you can
243 override the default timestamp display format by loading this
244 module and then redefining this function.
245 Most commonly, this function can be used in formatting callbacks.
247 AnyEvent::Log::default_format $time, $ctx, $level, $msg
249 Format a log message using the given timestamp, logging context,
250 log level and log message.
251 This is the formatting function used to format messages when no
253 custom function is provided.
254 In your main program (as opposed to in your module) you can
256 override the default message format by loading this module and then
257 redefining this function.
258 AnyEvent::Log::fatal_exit
260 This is the function that is called after logging a "fatal" log
261 message. It must not return.
262 The default implementation simply calls "exit 1".
264 In your main program (as opposed to in your module) you can
266 override the fatal exit function by loading this module and then
267 redefining this function. Make sure you don't return.
268
270 This module associates every log message with a so-called logging
271 context, based on the package of the caller. Every perl package has its
272 own logging context.
273 A logging context has three major responsibilities: filtering, logging
275 and propagating the message.
276 For the first purpose, filtering, each context has a set of logging
278 levels, called the log level mask. Messages not in the set will be
279 ignored by this context (masked).
280 For logging, the context stores a formatting callback (which takes the
282 timestamp, context, level and string message and formats it in the way
283 it should be logged) and a logging callback (which is responsible for
284 actually logging the formatted message and telling "AnyEvent::Log"
285 whether it has consumed the message, or whether it should be
286 propagated).
287 For propagation, a context can have any number of attached slave
289 contexts. Any message that is neither masked by the logging mask nor
290 masked by the logging callback returning true will be passed to all
291 slave contexts.
292 Each call to a logging function will log the message at most once per
294 context, so it does not matter (much) if there are cycles or if the
295 message can arrive at the same context via multiple paths.
296 DEFAULTS
298 By default, all logging contexts have an full set of log levels
299 ("all"), a disabled logging callback and the default formatting
300 callback.
301 Package contexts have the package name as logging title by default.
303 They have exactly one slave - the context of the "parent" package. The
305 parent package is simply defined to be the package name without the
306 last component, i.e. "AnyEvent::Debug::Wrapped" becomes
307 "AnyEvent::Debug", and "AnyEvent" becomes ... $AnyEvent::Log::COLLECT
308 which is the exception of the rule - just like the "parent" of any
309 single-component package name in Perl is "main", the default slave of
310 any top-level package context is $AnyEvent::Log::COLLECT.
311 Since perl packages form only an approximate hierarchy, this slave
313 context can of course be removed.
314 All other (anonymous) contexts have no slaves and an empty title by
316 default.
317 When the module is loaded it creates the $AnyEvent::Log::LOG logging
319 context that simply logs everything via "warn", without propagating
320 anything anywhere by default. The purpose of this context is to
321 provide a convenient place to override the global logging target or to
322 attach additional log targets. It's not meant for filtering.
323 It then creates the $AnyEvent::Log::FILTER context whose purpose is to
325 suppress all messages with priority higher than
326 $ENV{PERL_ANYEVENT_VERBOSE}. It then attached the $AnyEvent::Log::LOG
327 context to it. The purpose of the filter context is to simply provide
328 filtering according to some global log level.
329 Finally it creates the top-level package context
331 $AnyEvent::Log::COLLECT and attaches the $AnyEvent::Log::FILTER context
332 to it, but otherwise leaves it at default config. Its purpose is simply
333 to collect all log messages system-wide.
334 The hierarchy is then:
336 any package, eventually -> $COLLECT -> $FILTER -> $LOG
338 The effect of all this is that log messages, by default, wander up to
340 the $AnyEvent::Log::COLLECT context where all messages normally end up,
341 from there to $AnyEvent::Log::FILTER where log messages with lower
342 priority then $ENV{PERL_ANYEVENT_VERBOSE} will be filtered out and then
343 to the $AnyEvent::Log::LOG context to be passed to "warn".
344 This makes it easy to set a global logging level (by modifying
346 $FILTER), but still allow other contexts to send, for example, their
347 debug and trace messages to the $LOG target despite the global logging
348 level, or to attach additional log targets that log messages,
349 regardless of the global logging level.
350 It also makes it easy to modify the default warn-logger ($LOG) to
352 something that logs to a file, or to attach additional logging targets
353 (such as loggign to a file) by attaching it to $FILTER.
354 CREATING/FINDING/DESTROYING CONTEXTS
356 $ctx = AnyEvent::Log::ctx [$pkg]
357 This function creates or returns a logging context (which is an
358 object).
359 If a package name is given, then the context for that packlage is
361 returned. If it is called without any arguments, then the context
362 for the callers package is returned (i.e. the same context as a
363 "AE::log" call would use).
364 If "undef" is given, then it creates a new anonymous context that
366 is not tied to any package and is destroyed when no longer
367 referenced.
368 AnyEvent::Log::reset
370 Resets all package contexts and recreates the default hierarchy if
371 necessary, i.e. resets the logging subsystem to defaults, as much
372 as possible. This process keeps references to contexts held by
373 other parts of the program intact.
374 This can be used to implement config-file (re-)loading: before
376 loading a configuration, reset all contexts.
377 $ctx = new AnyEvent::Log::Ctx methodname => param...
379 This is a convenience constructor that makes it simpler to
380 construct anonymous logging contexts.
381 Each key-value pair results in an invocation of the method of the
383 same name as the key with the value as parameter, unless the value
384 is an arrayref, in which case it calls the method with the contents
385 of the array. The methods are called in the same order as
386 specified.
387 Example: create a new logging context and set both the default
389 logging level, some slave contexts and a logging callback.
390 $ctx = new AnyEvent::Log::Ctx
392 title => "dubious messages",
393 level => "error",
394 log_cb => sub { print STDOUT shift; 0 },
395 slaves => [$ctx1, $ctx, $ctx2],
396 ;
397 CONFIGURING A LOG CONTEXT
399 The following methods can be used to configure the logging context.
400 $ctx->title ([$new_title])
402 Returns the title of the logging context - this is the package
403 name, for package contexts, and a user defined string for all
404 others.
405 If $new_title is given, then it replaces the package name or title.
407 LOGGING LEVELS
409 The following methods deal with the logging level set associated with
411 the log context.
412 The most common method to use is probably "$ctx->level ($level)", which
414 configures the specified and any higher priority levels.
415 All functions which accept a list of levels also accept the special
417 string "all" which expands to all logging levels.
418 $ctx->levels ($level[, $level...)
420 Enables logging for the given levels and disables it for all
421 others.
422 $ctx->level ($level)
424 Enables logging for the given level and all lower level (higher
425 priority) ones. In addition to normal logging levels, specifying a
426 level of 0 or "off" disables all logging for this level.
427 Example: log warnings, errors and higher priority messages.
429 $ctx->level ("warn");
431 $ctx->level (5); # same thing, just numeric
432 $ctx->enable ($level[, $level...])
434 Enables logging for the given levels, leaving all others unchanged.
435 $ctx->disable ($level[, $level...])
437 Disables logging for the given levels, leaving all others
438 unchanged.
439 $ctx->cap ($level)
441 Caps the maximum priority to the given level, for all messages
442 logged to, or passing through, this context. That is, while this
443 doesn't affect whether a message is logged or passed on, the
444 maximum priority of messages will be limited to the specified level
445 - messages with a higher priority will be set to the specified
446 priority.
447 Another way to view this is that "->level" filters out messages
449 with a too low priority, while "->cap" modifies messages with a too
450 high priority.
451 This is useful when different log targets have different
453 interpretations of priority. For example, for a specific command
454 line program, a wrong command line switch might well result in a
455 "fatal" log message, while the same message, logged to syslog, is
456 likely not fatal to the system or syslog facility as a whole, but
457 more likely a mere "error".
458 This can be modeled by having a stderr logger that logs messages
460 "as-is" and a syslog logger that logs messages with a level cap of,
461 say, "error", or, for truly system-critical components, actually
462 "critical".
463 SLAVE CONTEXTS
465 The following methods attach and detach another logging context to a
467 logging context.
468 Log messages are propagated to all slave contexts, unless the logging
470 callback consumes the message.
471 $ctx->attach ($ctx2[, $ctx3...])
473 Attaches the given contexts as slaves to this context. It is not an
474 error to add a context twice (the second add will be ignored).
475 A context can be specified either as package name or as a context
477 object.
478 $ctx->detach ($ctx2[, $ctx3...])
480 Removes the given slaves from this context - it's not an error to
481 attempt to remove a context that hasn't been added.
482 A context can be specified either as package name or as a context
484 object.
485 $ctx->slaves ($ctx2[, $ctx3...])
487 Replaces all slaves attached to this context by the ones given.
488 LOG TARGETS
490 The following methods configure how the logging context actually does
492 the logging (which consists of formatting the message and printing it
493 or whatever it wants to do with it).
494 $ctx->log_cb ($cb->($str))
496 Replaces the logging callback on the context ("undef" disables the
497 logging callback).
498 The logging callback is responsible for handling formatted log
500 messages (see "fmt_cb" below) - normally simple text strings that
501 end with a newline (and are possibly multiline themselves).
502 It also has to return true iff it has consumed the log message, and
504 false if it hasn't. Consuming a message means that it will not be
505 sent to any slave context. When in doubt, return 0 from your
506 logging callback.
507 Example: a very simple logging callback, simply dump the message to
509 STDOUT and do not consume it.
510 $ctx->log_cb (sub { print STDERR shift; 0 });
512 You can filter messages by having a log callback that simply
514 returns 1 and does not do anything with the message, but this
515 counts as "message being logged" and might not be very efficient.
516 Example: propagate all messages except for log levels "debug" and
518 "trace". The messages will still be generated, though, which can
519 slow down your program.
520 $ctx->levels ("debug", "trace");
522 $ctx->log_cb (sub { 1 }); # do not log, but eat debug and trace messages
523 $ctx->fmt_cb ($fmt_cb->($timestamp, $orig_ctx, $level, $message))
525 Replaces the formatting callback on the context ("undef" restores
526 the default formatter).
527 The callback is passed the (possibly fractional) timestamp, the
529 original logging context (object, not title), the (numeric) logging
530 level and the raw message string and needs to return a formatted
531 log message. In most cases this will be a string, but it could just
532 as well be an array reference that just stores the values.
533 If, for some reason, you want to use "caller" to find out more
535 about the logger then you should walk up the call stack until you
536 are no longer inside the "AnyEvent::Log" package.
537 To implement your own logging callback, you might find the
539 "AnyEvent::Log::format_time" and "AnyEvent::Log::default_format"
540 functions useful.
541 Example: format the message just as AnyEvent::Log would, by letting
543 AnyEvent::Log do the work. This is a good basis to design a
544 formatting callback that only changes minor aspects of the
545 formatting.
546 $ctx->fmt_cb (sub {
548 my ($time, $ctx, $lvl, $msg) = @_;
549 AnyEvent::Log::default_format $time, $ctx, $lvl, $msg
551 });
552 Example: format just the raw message, with numeric log level in
554 angle brackets.
555 $ctx->fmt_cb (sub {
557 my ($time, $ctx, $lvl, $msg) = @_;
558 "<$lvl>$msg\n"
560 });
561 Example: return an array reference with just the log values, and
563 use "PApp::SQL::sql_exec" to store the message in a database.
564 $ctx->fmt_cb (sub { \@_ });
566 $ctx->log_cb (sub {
567 my ($msg) = @_;
568 sql_exec "insert into log (when, subsys, prio, msg) values (?, ?, ?, ?)",
570 $msg->[0] + 0,
571 "$msg->[1]",
572 $msg->[2] + 0,
573 "$msg->[3]";
574 0
576 });
577 $ctx->log_to_warn
579 Sets the "log_cb" to simply use "CORE::warn" to report any messages
580 (usually this logs to STDERR).
581 $ctx->log_to_file ($path)
583 Sets the "log_cb" to log to a file (by appending), unbuffered. The
584 function might return before the log file has been opened or
585 created.
586 $ctx->log_to_path ($path)
588 Same as "->log_to_file", but opens the file for each message. This
589 is much slower, but allows you to change/move/rename/delete the
590 file at basically any time.
591 Needless(?) to say, if you do not want to be bitten by some evil
593 person calling "chdir", the path should be absolute. Doesn't help
594 with "chroot", but hey...
595 $ctx->log_to_syslog ([$facility])
597 Logs all messages via Sys::Syslog, mapping "trace" to "debug" and
598 all the others in the obvious way. If specified, then the $facility
599 is used as the facility ("user", "auth", "local0" and so on). The
600 default facility is "user".
601 Note that this function also sets a "fmt_cb" - the logging part
603 requires an array reference with [$level, $str] as input.
604 MESSAGE LOGGING
606 These methods allow you to log messages directly to a context, without
608 going via your package context.
609 $ctx->log ($level, $msg[, @params])
611 Same as "AnyEvent::Log::log", but uses the given context as log
612 context.
613 Example: log a message in the context of another package.
615 (AnyEvent::Log::ctx "Other::Package")->log (warn => "heely bo");
617 $logger = $ctx->logger ($level[, \$enabled])
619 Same as "AnyEvent::Log::logger", but uses the given context as log
620 context.
621
623 Logging can also be configured by setting the environment variable
624 "PERL_ANYEVENT_LOG" (or "AE_LOG").
625 The value consists of one or more logging context specifications
627 separated by ":" or whitespace. Each logging specification in turn
628 starts with a context name, followed by "=", followed by zero or more
629 comma-separated configuration directives, here are some examples:
630 # set default logging level
632 filter=warn
633 # log to file instead of to stderr
635 log=file=/tmp/mylog
636 # log to file in addition to stderr
638 log=+%file:%file=file=/tmp/mylog
639 # enable debug log messages, log warnings and above to syslog
641 filter=debug:log=+%warnings:%warnings=warn,syslog=LOG_LOCAL0
642 # log trace messages (only) from AnyEvent::Debug to file
644 AnyEvent::Debug=+%trace:%trace=only,trace,file=/tmp/tracelog
645 A context name in the log specification can be any of the following:
647 "collect", "filter", "log"
649 Correspond to the three predefined $AnyEvent::Log::COLLECT,
650 "AnyEvent::Log::FILTER" and $AnyEvent::Log::LOG contexts.
651 %name
653 Context names starting with a "%" are anonymous contexts created
654 when the name is first mentioned. The difference to package
655 contexts is that by default they have no attached slaves.
656 This makes it possible to create new log contexts that can be
658 refered to multiple times by name within the same log
659 specification.
660 a perl package name
662 Any other string references the logging context associated with the
663 given Perl "package". In the unlikely case where you want to
664 specify a package context that matches on of the other context name
665 forms, you can add a "::" to the package name to force
666 interpretation as a package.
667 The configuration specifications can be any number of the following:
669 "stderr"
671 Configures the context to use Perl's "warn" function (which
672 typically logs to "STDERR"). Works like "log_to_warn".
673 "file="path
675 Configures the context to log to a file with the given path. Works
676 like "log_to_file".
677 "path="path
679 Configures the context to log to a file with the given path. Works
680 like "log_to_path".
681 "syslog" or "syslog="expr
683 Configures the context to log to syslog. If expr is given, then it
684 is evaluated in the Sys::Syslog package, so you could use:
685 log=syslog=LOG_LOCAL0
687 "nolog"
689 Configures the context to not log anything by itself, which is the
690 default. Same as "$ctx->log_cb (undef)".
691 "cap="level
693 Caps logging messages entering this context at the given level,
694 i.e. reduces the priority of messages with higher priority than
695 this level. The default is 0 (or "off"), meaning the priority will
696 not be touched.
697 0 or "off"
699 Sets the logging level of the context to 0, i.e. all messages will
700 be filtered out.
701 "all"
703 Enables all logging levels, i.e. filtering will effectively be
704 switched off (the default).
705 "only"
707 Disables all logging levels, and changes the interpretation of
708 following level specifications to enable the specified level only.
709 Example: only enable debug messages for a context.
711 context=only,debug
713 "except"
715 Enables all logging levels, and changes the interpretation of
716 following level specifications to disable that level. Rarely used.
717 Example: enable all logging levels except fatal and trace (this is
719 rather nonsensical).
720 filter=exept,fatal,trace
722 "level"
724 Enables all logging levels, and changes the interpretation of
725 following level specifications to be "that level or any higher
726 priority message". This is the default.
727 Example: log anything at or above warn level.
729 filter=warn
731 # or, more verbose
733 filter=only,level,warn
734 1..9 or a logging level name ("error", "debug" etc.)
736 A numeric loglevel or the name of a loglevel will be interpreted
737 according to the most recent "only", "except" or "level" directive.
738 By default, specifying a logging level enables that and any higher
739 priority messages.
740 "+"context
742 Attaches the named context as slave to the context.
743 "+" A lone "+" detaches all contexts, i.e. clears the slave list from
745 the context. Anonymous (%name) contexts have no attached slaves by
746 default, but package contexts have the parent context as slave by
747 default.
748 Example: log messages from My::Module to a file, do not send them
750 to the default log collector.
751 My::Module=+,file=/tmp/mymodulelog
753 Any character can be escaped by prefixing it with a "\" (backslash), as
755 usual, so to log to a file containing a comma, colon, backslash and
756 some spaces in the filename, you would do this:
757 PERL_ANYEVENT_LOG='log=file=/some\ \:file\ with\,\ \\-escapes'
759 Since whitespace (which includes newlines) is allowed, it is fine to
761 specify multiple lines in "PERL_ANYEVENT_LOG", e.g.:
762 PERL_ANYEVENT_LOG="
764 filter=warn
765 AnyEvent::Debug=+%trace
766 %trace=only,trace,+log
767 " myprog
768 Also, in the unlikely case when you want to concatenate specifications,
770 use whitespace as separator, as "::" will be interpreted as part of a
771 module name, an empty spec with two separators:
772 PERL_ANYEVENT_LOG="$PERL_ANYEVENT_LOG MyMod=debug"
774
776 This section shows some common configurations, both as code, and as
777 "PERL_ANYEVENT_LOG" string.
778 Setting the global logging level.
780 Either put "PERL_ANYEVENT_VERBOSE="<number> into your environment
781 before running your program, use "PERL_ANYEVENT_LOG" or modify the
782 log level of the root context at runtime:
783 PERL_ANYEVENT_VERBOSE=5 ./myprog
785 PERL_ANYEVENT_LOG=log=warn
787 $AnyEvent::Log::FILTER->level ("warn");
789 Append all messages to a file instead of sending them to STDERR.
791 This is affected by the global logging level.
792 $AnyEvent::Log::LOG->log_to_file ($path);
794 PERL_ANYEVENT_LOG=log=file=/some/path
796 Write all messages with priority "error" and higher to a file.
798 This writes them only when the global logging level allows it,
799 because it is attached to the default context which is invoked
800 after global filtering.
801 $AnyEvent::Log::FILTER->attach (
803 new AnyEvent::Log::Ctx log_to_file => $path);
804 PERL_ANYEVENT_LOG=filter=+%filelogger:%filelogger=file=/some/path
806 This writes them regardless of the global logging level, because it
808 is attached to the toplevel context, which receives all messages
809 before the global filtering.
810 $AnyEvent::Log::COLLECT->attach (
812 new AnyEvent::Log::Ctx log_to_file => $path);
813 PERL_ANYEVENT_LOG=%filelogger=file=/some/path:collect=+%filelogger
815 In both cases, messages are still written to STDERR.
817 Additionally log all messages with "warn" and higher priority to
819 "syslog", but cap at "error".
820 This logs all messages to the default log target, but also logs
821 messages with priority "warn" or higher (and not filtered
822 otherwise) to syslog facility "user". Messages with priority higher
823 than "error" will be logged with level "error".
824 $AnyEvent::Log::LOG->attach (
826 new AnyEvent::Log::Ctx
827 level => "warn",
828 cap => "error",
829 syslog => "user",
830 );
831 PERL_ANYEVENT_LOG=log=+%syslog:%syslog=warn,cap=error,syslog
833 Write trace messages (only) from AnyEvent::Debug to the default logging
835 target(s).
836 Attach the $AnyEvent::Log::LOG context to the "AnyEvent::Debug"
837 context - this simply circumvents the global filtering for trace
838 messages.
839 my $debug = AnyEvent::Debug->AnyEvent::Log::ctx;
841 $debug->attach ($AnyEvent::Log::LOG);
842 PERL_ANYEVENT_LOG=AnyEvent::Debug=+log
844 This of course works for any package, not just AnyEvent::Debug, but
846 assumes the log level for AnyEvent::Debug hasn't been changed from
847 the default.
848
850 This module uses AnyEvent::IO to actually write log messages (in
851 "log_to_file" and "log_to_path"), so it doesn't block your program when
852 the disk is busy and a non-blocking AnyEvent::IO backend is available.
853
855 Marc Lehmann <schmorp@schmorp.de>
856 http://anyevent.schmorp.de
857perl v5.28.0 2016-03-13 AnyEvent::Log(3)