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 is too hot!";
16 AE::log error => "Division by zero attempted.";
17 AE::log warn => "Couldn't delete the file.";
18 AE::log note => "Attempted 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 default logging level to suppress anything below "notice"
48 # i.e. enable logging at "notice" or above - the default is to
49 # to not log anything at all.
50 $AnyEvent::Log::FILTER->level ("notice");
51 # set logging for the current package to errors and higher only
53 AnyEvent::Log::ctx->level ("error");
54 # enable logging for the current package, regardless of global logging level
56 AnyEvent::Log::ctx->attach ($AnyEvent::Log::LOG);
57 # enable debug logging for module some::mod and enable logging by default
59 (AnyEvent::Log::ctx "some::mod")->level ("debug");
60 (AnyEvent::Log::ctx "some::mod")->attach ($AnyEvent::Log::LOG);
61 # send all critical and higher priority messages to syslog,
63 # regardless of (most) other settings
64 $AnyEvent::Log::COLLECT->attach (new AnyEvent::Log::Ctx
65 level => "critical",
66 log_to_syslog => "user",
67 );
68
70 This module implements a relatively simple "logging framework". It
71 doesn't attempt to be "the" logging solution or even "a" logging
72 solution for AnyEvent - AnyEvent simply creates logging messages
73 internally, and this module more or less exposes the mechanism, with
74 some extra spiff to allow using it from other modules as well.
75 Remember that the default verbosity level is 4 ("error"), so only
77 errors and more important messages will be logged, unless you set
78 "PERL_ANYEVENT_VERBOSE" to a higher number before starting your program
79 ("AE_VERBOSE=5" is recommended during development), or change the
80 logging level at runtime with something like:
81 use AnyEvent::Log;
83 $AnyEvent::Log::FILTER->level ("info");
84 The design goal behind this module was to keep it simple (and small),
86 but make it powerful enough to be potentially useful for any module,
87 and extensive enough for the most common tasks, such as logging to
88 multiple targets, or being able to log into a database.
89 The module is also usable before AnyEvent itself is initialised, in
91 which case some of the functionality might be reduced.
92 The amount of documentation might indicate otherwise, but the runtime
94 part of the module is still just below 300 lines of code.
95
97 Logging levels in this module range from 1 (highest priority) to 9
98 (lowest priority). Note that the lowest numerical value is the highest
99 priority, so when this document says "higher priority" it means "lower
100 numerical value".
101 Instead of specifying levels by name you can also specify them by
103 aliases:
104 LVL NAME SYSLOG PERL NOTE
106 1 fatal emerg exit system unusable, aborts program!
107 2 alert failure in primary system
108 3 critical crit failure in backup system
109 4 error err die non-urgent program errors, a bug
110 5 warn warning possible problem, not necessarily error
111 6 note notice unusual conditions
112 7 info normal messages, no action required
113 8 debug debugging messages for development
114 9 trace copious tracing output
115 As you can see, some logging levels have multiple aliases - the first
117 one is the "official" name, the second one the "syslog" name (if it
118 differs) and the third one the "perl" name, suggesting (only!) that you
119 log "die" messages at "error" priority. The NOTE column tries to
120 provide some rationale on how to chose a logging level.
121 As a rough guideline, levels 1..3 are primarily meant for users of the
123 program (admins, staff), and are the only ones logged to STDERR by
124 default. Levels 4..6 are meant for users and developers alike, while
125 levels 7..9 are usually meant for developers.
126 You can normally only log a message once at highest priority level (1,
128 "fatal"), because logging a fatal message will also quit the program -
129 so use it sparingly :)
130 For example, a program that finds an unknown switch on the commandline
132 might well use a fatal logging level to tell users about it - the
133 "system" in this case would be the program, or module.
134 Some methods also offer some extra levels, such as 0, "off", "none" or
136 "all" - these are only valid for the methods that documented them.
137
139 The following functions allow you to log messages. They always use the
140 caller's package as a "logging context". Also, the main logging
141 function, "log", is aliased to "AnyEvent::log" and "AE::log" when the
142 "AnyEvent" module is loaded.
143 AnyEvent::Log::log $level, $msg[, @args]
145 Requests logging of the given $msg with the given log level, and
146 returns true if the message was logged somewhere.
147 For loglevel "fatal", the program will abort.
149 If only a $msg is given, it is logged as-is. With extra @args, the
151 $msg is interpreted as an sprintf format string.
152 The $msg should not end with "\n", but may if that is convenient
154 for you. Also, multiline messages are handled properly.
155 Last not least, $msg might be a code reference, in which case it is
157 supposed to return the message. It will be called only then the
158 message actually gets logged, which is useful if it is costly to
159 create the message in the first place.
160 This function takes care of saving and restoring $! and $@, so you
162 don't have to.
163 Whether the given message will be logged depends on the maximum log
165 level and the caller's package. The return value can be used to
166 ensure that messages or not "lost" - for example, when
167 AnyEvent::Debug detects a runtime error it tries to log it at "die"
168 level, but if that message is lost it simply uses warn.
169 Note that you can (and should) call this function as
171 "AnyEvent::log" or "AE::log", without "use"-ing this module if
172 possible (i.e. you don't need any additional functionality), as
173 those functions will load the logging module on demand only. They
174 are also much shorter to write.
175 Also, if you optionally generate a lot of debug messages (such as
177 when tracing some code), you should look into using a logger
178 callback and a boolean enabler (see "logger", below).
179 Example: log something at error level.
181 AE::log error => "something";
183 Example: use printf-formatting.
185 AE::log info => "%5d %-10.10s %s", $index, $category, $msg;
187 Example: only generate a costly dump when the message is actually
189 being logged.
190 AE::log debug => sub { require Data::Dump; Data::Dump::dump \%cache };
192 $logger = AnyEvent::Log::logger $level[, \$enabled]
194 Creates a code reference that, when called, acts as if the
195 "AnyEvent::Log::log" function was called at this point with the
196 given level. $logger is passed a $msg and optional @args, just as
197 with the "AnyEvent::Log::log" function:
198 my $debug_log = AnyEvent::Log::logger "debug";
200 $debug_log->("debug here");
202 $debug_log->("%06d emails processed", 12345);
203 $debug_log->(sub { $obj->as_string });
204 The idea behind this function is to decide whether to log before
206 actually logging - when the "logger" function is called once, but
207 the returned logger callback often, then this can be a tremendous
208 speed win.
209 Despite this speed advantage, changes in logging configuration will
211 still be reflected by the logger callback, even if configuration
212 changes after it was created.
213 To further speed up logging, you can bind a scalar variable to the
215 logger, which contains true if the logger should be called or not -
216 if it is false, calling the logger can be safely skipped. This
217 variable will be updated as long as $logger is alive.
218 Full example:
220 # near the init section
222 use AnyEvent::Log;
223 my $debug_log = AnyEvent:Log::logger debug => \my $debug;
225 # and later in your program
227 $debug_log->("yo, stuff here") if $debug;
228 $debug and $debug_log->("123");
230 AnyEvent::Log::exact_time $on
232 By default, "AnyEvent::Log" will use "AE::now", i.e. the cached
233 eventloop time, for the log timestamps. After calling this function
234 with a true value it will instead resort to "AE::time", i.e. fetch
235 the current time on each log message. This only makes a difference
236 for event loops that actually cache the time (such as EV or
237 AnyEvent::Loop).
238 This setting can be changed at any time by calling this function.
240 Since "AnyEvent::Log" has to work even before the AnyEvent has been
242 initialised, this switch will also decide whether to use
243 "CORE::time" or "Time::HiRes::time" when logging a message before
244 AnyEvent becomes available.
245 AnyEvent::Log::format_time $timestamp
247 Formats a timestamp as returned by "AnyEvent->now" or
248 "AnyEvent->time" or many other functions in the same way as
249 "AnyEvent::Log" does.
250 In your main program (as opposed to in your module) you can
252 override the default timestamp display format by loading this
253 module and then redefining this function.
254 Most commonly, this function can be used in formatting callbacks.
256 AnyEvent::Log::default_format $time, $ctx, $level, $msg
258 Format a log message using the given timestamp, logging context,
259 log level and log message.
260 This is the formatting function used to format messages when no
262 custom function is provided.
263 In your main program (as opposed to in your module) you can
265 override the default message format by loading this module and then
266 redefining this function.
267 AnyEvent::Log::fatal_exit()
269 This is the function that is called after logging a "fatal" log
270 message. It must not return.
271 The default implementation simply calls "exit 1".
273 In your main program (as opposed to in your module) you can
275 override the fatal exit function by loading this module and then
276 redefining this function. Make sure you don't return.
277
279 This module associates every log message with a so-called logging
280 context, based on the package of the caller. Every perl package has its
281 own logging context.
282 A logging context has three major responsibilities: filtering, logging
284 and propagating the message.
285 For the first purpose, filtering, each context has a set of logging
287 levels, called the log level mask. Messages not in the set will be
288 ignored by this context (masked).
289 For logging, the context stores a formatting callback (which takes the
291 timestamp, context, level and string message and formats it in the way
292 it should be logged) and a logging callback (which is responsible for
293 actually logging the formatted message and telling "AnyEvent::Log"
294 whether it has consumed the message, or whether it should be
295 propagated).
296 For propagation, a context can have any number of attached slave
298 contexts. Any message that is neither masked by the logging mask nor
299 masked by the logging callback returning true will be passed to all
300 slave contexts.
301 Each call to a logging function will log the message at most once per
303 context, so it does not matter (much) if there are cycles or if the
304 message can arrive at the same context via multiple paths.
305 DEFAULTS
307 By default, all logging contexts have an full set of log levels
308 ("all"), a disabled logging callback and the default formatting
309 callback.
310 Package contexts have the package name as logging title by default.
312 They have exactly one slave - the context of the "parent" package. The
314 parent package is simply defined to be the package name without the
315 last component, i.e. "AnyEvent::Debug::Wrapped" becomes
316 "AnyEvent::Debug", and "AnyEvent" becomes ... $AnyEvent::Log::COLLECT
317 which is the exception of the rule - just like the "parent" of any
318 single-component package name in Perl is "main", the default slave of
319 any top-level package context is $AnyEvent::Log::COLLECT.
320 Since perl packages form only an approximate hierarchy, this slave
322 context can of course be removed.
323 All other (anonymous) contexts have no slaves and an empty title by
325 default.
326 When the module is loaded it creates the $AnyEvent::Log::LOG logging
328 context that simply logs everything via "warn", without propagating
329 anything anywhere by default. The purpose of this context is to
330 provide a convenient place to override the global logging target or to
331 attach additional log targets. It's not meant for filtering.
332 It then creates the $AnyEvent::Log::FILTER context whose purpose is to
334 suppress all messages with priority higher than
335 $ENV{PERL_ANYEVENT_VERBOSE}. It then attached the $AnyEvent::Log::LOG
336 context to it. The purpose of the filter context is to simply provide
337 filtering according to some global log level.
338 Finally it creates the top-level package context
340 $AnyEvent::Log::COLLECT and attaches the $AnyEvent::Log::FILTER context
341 to it, but otherwise leaves it at default config. Its purpose is simply
342 to collect all log messages system-wide.
343 The hierarchy is then:
345 any package, eventually -> $COLLECT -> $FILTER -> $LOG
347 The effect of all this is that log messages, by default, wander up to
349 the $AnyEvent::Log::COLLECT context where all messages normally end up,
350 from there to $AnyEvent::Log::FILTER where log messages with lower
351 priority then $ENV{PERL_ANYEVENT_VERBOSE} will be filtered out and then
352 to the $AnyEvent::Log::LOG context to be passed to "warn".
353 This makes it easy to set a global logging level (by modifying
355 $FILTER), but still allow other contexts to send, for example, their
356 debug and trace messages to the $LOG target despite the global logging
357 level, or to attach additional log targets that log messages,
358 regardless of the global logging level.
359 It also makes it easy to modify the default warn-logger ($LOG) to
361 something that logs to a file, or to attach additional logging targets
362 (such as loggign to a file) by attaching it to $FILTER.
363 CREATING/FINDING/DESTROYING CONTEXTS
365 $ctx = AnyEvent::Log::ctx [$pkg]
366 This function creates or returns a logging context (which is an
367 object).
368 If a package name is given, then the context for that package is
370 returned. If it is called without any arguments, then the context
371 for the callers package is returned (i.e. the same context as a
372 "AE::log" call would use).
373 If "undef" is given, then it creates a new anonymous context that
375 is not tied to any package and is destroyed when no longer
376 referenced.
377 AnyEvent::Log::reset
379 Resets all package contexts and recreates the default hierarchy if
380 necessary, i.e. resets the logging subsystem to defaults, as much
381 as possible. This process keeps references to contexts held by
382 other parts of the program intact.
383 This can be used to implement config-file (re-)loading: before
385 loading a configuration, reset all contexts.
386 $ctx = new AnyEvent::Log::Ctx methodname => param...
388 This is a convenience constructor that makes it simpler to
389 construct anonymous logging contexts.
390 Each key-value pair results in an invocation of the method of the
392 same name as the key with the value as parameter, unless the value
393 is an arrayref, in which case it calls the method with the contents
394 of the array. The methods are called in the same order as
395 specified.
396 Example: create a new logging context and set both the default
398 logging level, some slave contexts and a logging callback.
399 $ctx = new AnyEvent::Log::Ctx
401 title => "dubious messages",
402 level => "error",
403 log_cb => sub { print STDOUT shift; 0 },
404 slaves => [$ctx1, $ctx, $ctx2],
405 ;
406 CONFIGURING A LOG CONTEXT
408 The following methods can be used to configure the logging context.
409 $ctx->title ([$new_title])
411 Returns the title of the logging context - this is the package
412 name, for package contexts, and a user defined string for all
413 others.
414 If $new_title is given, then it replaces the package name or title.
416 LOGGING LEVELS
418 The following methods deal with the logging level set associated with
420 the log context.
421 The most common method to use is probably "$ctx->level ($level)", which
423 configures the specified and any higher priority levels.
424 All functions which accept a list of levels also accept the special
426 string "all" which expands to all logging levels.
427 $ctx->levels ($level[, $level...)
429 Enables logging for the given levels and disables it for all
430 others.
431 $ctx->level ($level)
433 Enables logging for the given level and all lower level (higher
434 priority) ones. In addition to normal logging levels, specifying a
435 level of 0 or "off" disables all logging for this level.
436 Example: log warnings, errors and higher priority messages.
438 $ctx->level ("warn");
440 $ctx->level (5); # same thing, just numeric
441 $ctx->enable ($level[, $level...])
443 Enables logging for the given levels, leaving all others unchanged.
444 $ctx->disable ($level[, $level...])
446 Disables logging for the given levels, leaving all others
447 unchanged.
448 $ctx->cap ($level)
450 Caps the maximum priority to the given level, for all messages
451 logged to, or passing through, this context. That is, while this
452 doesn't affect whether a message is logged or passed on, the
453 maximum priority of messages will be limited to the specified level
454 - messages with a higher priority will be set to the specified
455 priority.
456 Another way to view this is that "->level" filters out messages
458 with a too low priority, while "->cap" modifies messages with a too
459 high priority.
460 This is useful when different log targets have different
462 interpretations of priority. For example, for a specific command
463 line program, a wrong command line switch might well result in a
464 "fatal" log message, while the same message, logged to syslog, is
465 likely not fatal to the system or syslog facility as a whole, but
466 more likely a mere "error".
467 This can be modeled by having a stderr logger that logs messages
469 "as-is" and a syslog logger that logs messages with a level cap of,
470 say, "error", or, for truly system-critical components, actually
471 "critical".
472 SLAVE CONTEXTS
474 The following methods attach and detach another logging context to a
476 logging context.
477 Log messages are propagated to all slave contexts, unless the logging
479 callback consumes the message.
480 $ctx->attach ($ctx2[, $ctx3...])
482 Attaches the given contexts as slaves to this context. It is not an
483 error to add a context twice (the second add will be ignored).
484 A context can be specified either as package name or as a context
486 object.
487 $ctx->detach ($ctx2[, $ctx3...])
489 Removes the given slaves from this context - it's not an error to
490 attempt to remove a context that hasn't been added.
491 A context can be specified either as package name or as a context
493 object.
494 $ctx->slaves ($ctx2[, $ctx3...])
496 Replaces all slaves attached to this context by the ones given.
497 LOG TARGETS
499 The following methods configure how the logging context actually does
501 the logging (which consists of formatting the message and printing it
502 or whatever it wants to do with it).
503 $ctx->log_cb ($cb->($str))
505 Replaces the logging callback on the context ("undef" disables the
506 logging callback).
507 The logging callback is responsible for handling formatted log
509 messages (see "fmt_cb" below) - normally simple text strings that
510 end with a newline (and are possibly multiline themselves).
511 It also has to return true iff it has consumed the log message, and
513 false if it hasn't. Consuming a message means that it will not be
514 sent to any slave context. When in doubt, return 0 from your
515 logging callback.
516 Example: a very simple logging callback, simply dump the message to
518 STDOUT and do not consume it.
519 $ctx->log_cb (sub { print STDERR shift; 0 });
521 You can filter messages by having a log callback that simply
523 returns 1 and does not do anything with the message, but this
524 counts as "message being logged" and might not be very efficient.
525 Example: propagate all messages except for log levels "debug" and
527 "trace". The messages will still be generated, though, which can
528 slow down your program.
529 $ctx->levels ("debug", "trace");
531 $ctx->log_cb (sub { 1 }); # do not log, but eat debug and trace messages
532 $ctx->fmt_cb ($fmt_cb->($timestamp, $orig_ctx, $level, $message))
534 Replaces the formatting callback on the context ("undef" restores
535 the default formatter).
536 The callback is passed the (possibly fractional) timestamp, the
538 original logging context (object, not title), the (numeric) logging
539 level and the raw message string and needs to return a formatted
540 log message. In most cases this will be a string, but it could just
541 as well be an array reference that just stores the values.
542 If, for some reason, you want to use "caller" to find out more
544 about the logger then you should walk up the call stack until you
545 are no longer inside the "AnyEvent::Log" package.
546 To implement your own logging callback, you might find the
548 "AnyEvent::Log::format_time" and "AnyEvent::Log::default_format"
549 functions useful.
550 Example: format the message just as AnyEvent::Log would, by letting
552 AnyEvent::Log do the work. This is a good basis to design a
553 formatting callback that only changes minor aspects of the
554 formatting.
555 $ctx->fmt_cb (sub {
557 my ($time, $ctx, $lvl, $msg) = @_;
558 AnyEvent::Log::default_format $time, $ctx, $lvl, $msg
560 });
561 Example: format just the raw message, with numeric log level in
563 angle brackets.
564 $ctx->fmt_cb (sub {
566 my ($time, $ctx, $lvl, $msg) = @_;
567 "<$lvl>$msg\n"
569 });
570 Example: return an array reference with just the log values, and
572 use "PApp::SQL::sql_exec" to store the message in a database.
573 $ctx->fmt_cb (sub { \@_ });
575 $ctx->log_cb (sub {
576 my ($msg) = @_;
577 sql_exec "insert into log (when, subsys, prio, msg) values (?, ?, ?, ?)",
579 $msg->[0] + 0,
580 "$msg->[1]",
581 $msg->[2] + 0,
582 "$msg->[3]";
583 0
585 });
586 $ctx->log_to_warn
588 Sets the "log_cb" to simply use "CORE::warn" to report any messages
589 (usually this logs to STDERR).
590 $ctx->log_to_file ($path)
592 Sets the "log_cb" to log to a file (by appending), unbuffered. The
593 function might return before the log file has been opened or
594 created.
595 $ctx->log_to_path ($path)
597 Same as "->log_to_file", but opens the file for each message. This
598 is much slower, but allows you to change/move/rename/delete the
599 file at basically any time.
600 Needless(?) to say, if you do not want to be bitten by some evil
602 person calling "chdir", the path should be absolute. Doesn't help
603 with "chroot", but hey...
604 $ctx->log_to_syslog ([$facility])
606 Logs all messages via Sys::Syslog, mapping "trace" to "debug" and
607 all the others in the obvious way. If specified, then the $facility
608 is used as the facility ("user", "auth", "local0" and so on). The
609 default facility is "user".
610 Note that this function also sets a "fmt_cb" - the logging part
612 requires an array reference with [$level, $str] as input.
613 MESSAGE LOGGING
615 These methods allow you to log messages directly to a context, without
617 going via your package context.
618 $ctx->log ($level, $msg[, @params])
620 Same as "AnyEvent::Log::log", but uses the given context as log
621 context.
622 Example: log a message in the context of another package.
624 (AnyEvent::Log::ctx "Other::Package")->log (warn => "heely bo");
626 $logger = $ctx->logger ($level[, \$enabled])
628 Same as "AnyEvent::Log::logger", but uses the given context as log
629 context.
630
632 Logging can also be configured by setting the environment variable
633 "PERL_ANYEVENT_LOG" (or "AE_LOG").
634 The value consists of one or more logging context specifications
636 separated by ":" or whitespace. Each logging specification in turn
637 starts with a context name, followed by "=", followed by zero or more
638 comma-separated configuration directives, here are some examples:
639 # set default logging level
641 filter=warn
642 # log to file instead of to stderr
644 log=file=/tmp/mylog
645 # log to file in addition to stderr
647 log=+%file:%file=file=/tmp/mylog
648 # enable debug log messages, log warnings and above to syslog
650 filter=debug:log=+%warnings:%warnings=warn,syslog=LOG_LOCAL0
651 # log trace messages (only) from AnyEvent::Debug to file
653 AnyEvent::Debug=+%trace:%trace=only,trace,file=/tmp/tracelog
654 A context name in the log specification can be any of the following:
656 "collect", "filter", "log"
658 Correspond to the three predefined $AnyEvent::Log::COLLECT,
659 "AnyEvent::Log::FILTER" and $AnyEvent::Log::LOG contexts.
660 %name
662 Context names starting with a "%" are anonymous contexts created
663 when the name is first mentioned. The difference to package
664 contexts is that by default they have no attached slaves.
665 This makes it possible to create new log contexts that can be
667 refered to multiple times by name within the same log
668 specification.
669 a perl package name
671 Any other string references the logging context associated with the
672 given Perl "package". In the unlikely case where you want to
673 specify a package context that matches on of the other context name
674 forms, you can add a "::" to the package name to force
675 interpretation as a package.
676 The configuration specifications can be any number of the following:
678 "stderr"
680 Configures the context to use Perl's "warn" function (which
681 typically logs to "STDERR"). Works like "log_to_warn".
682 "file="path
684 Configures the context to log to a file with the given path. Works
685 like "log_to_file".
686 "path="path
688 Configures the context to log to a file with the given path. Works
689 like "log_to_path".
690 "syslog" or "syslog="expr
692 Configures the context to log to syslog. If expr is given, then it
693 is evaluated in the Sys::Syslog package, so you could use:
694 log=syslog=LOG_LOCAL0
696 "nolog"
698 Configures the context to not log anything by itself, which is the
699 default. Same as "$ctx->log_cb (undef)".
700 "cap="level
702 Caps logging messages entering this context at the given level,
703 i.e. reduces the priority of messages with higher priority than
704 this level. The default is 0 (or "off"), meaning the priority will
705 not be touched.
706 0 or "off"
708 Sets the logging level of the context to 0, i.e. all messages will
709 be filtered out.
710 "all"
712 Enables all logging levels, i.e. filtering will effectively be
713 switched off (the default).
714 "only"
716 Disables all logging levels, and changes the interpretation of
717 following level specifications to enable the specified level only.
718 Example: only enable debug messages for a context.
720 context=only,debug
722 "except"
724 Enables all logging levels, and changes the interpretation of
725 following level specifications to disable that level. Rarely used.
726 Example: enable all logging levels except fatal and trace (this is
728 rather nonsensical).
729 filter=exept,fatal,trace
731 "level"
733 Enables all logging levels, and changes the interpretation of
734 following level specifications to be "that level or any higher
735 priority message". This is the default.
736 Example: log anything at or above warn level.
738 filter=warn
740 # or, more verbose
742 filter=only,level,warn
743 1..9 or a logging level name ("error", "debug" etc.)
745 A numeric loglevel or the name of a loglevel will be interpreted
746 according to the most recent "only", "except" or "level" directive.
747 By default, specifying a logging level enables that and any higher
748 priority messages.
749 "+"context
751 Attaches the named context as slave to the context.
752 "+" A lone "+" detaches all contexts, i.e. clears the slave list from
754 the context. Anonymous (%name) contexts have no attached slaves by
755 default, but package contexts have the parent context as slave by
756 default.
757 Example: log messages from My::Module to a file, do not send them
759 to the default log collector.
760 My::Module=+,file=/tmp/mymodulelog
762 Any character can be escaped by prefixing it with a "\" (backslash), as
764 usual, so to log to a file containing a comma, colon, backslash and
765 some spaces in the filename, you would do this:
766 PERL_ANYEVENT_LOG='log=file=/some\ \:file\ with\,\ \\-escapes'
768 Since whitespace (which includes newlines) is allowed, it is fine to
770 specify multiple lines in "PERL_ANYEVENT_LOG", e.g.:
771 PERL_ANYEVENT_LOG="
773 filter=warn
774 AnyEvent::Debug=+%trace
775 %trace=only,trace,+log
776 " myprog
777 Also, in the unlikely case when you want to concatenate specifications,
779 use whitespace as separator, as "::" will be interpreted as part of a
780 module name, an empty spec with two separators:
781 PERL_ANYEVENT_LOG="$PERL_ANYEVENT_LOG MyMod=debug"
783
785 This section shows some common configurations, both as code, and as
786 "PERL_ANYEVENT_LOG" string.
787 Setting the global logging level.
789 Either put "PERL_ANYEVENT_VERBOSE="<number> into your environment
790 before running your program, use "PERL_ANYEVENT_LOG" or modify the
791 log level of the root context at runtime:
792 PERL_ANYEVENT_VERBOSE=5 ./myprog
794 PERL_ANYEVENT_LOG=log=warn
796 $AnyEvent::Log::FILTER->level ("warn");
798 Append all messages to a file instead of sending them to STDERR.
800 This is affected by the global logging level.
801 $AnyEvent::Log::LOG->log_to_file ($path);
803 PERL_ANYEVENT_LOG=log=file=/some/path
805 Write all messages with priority "error" and higher to a file.
807 This writes them only when the global logging level allows it,
808 because it is attached to the default context which is invoked
809 after global filtering.
810 $AnyEvent::Log::FILTER->attach (
812 new AnyEvent::Log::Ctx log_to_file => $path);
813 PERL_ANYEVENT_LOG=filter=+%filelogger:%filelogger=file=/some/path
815 This writes them regardless of the global logging level, because it
817 is attached to the toplevel context, which receives all messages
818 before the global filtering.
819 $AnyEvent::Log::COLLECT->attach (
821 new AnyEvent::Log::Ctx log_to_file => $path);
822 PERL_ANYEVENT_LOG=%filelogger=file=/some/path:collect=+%filelogger
824 In both cases, messages are still written to STDERR.
826 Additionally log all messages with "warn" and higher priority to
828 "syslog", but cap at "error".
829 This logs all messages to the default log target, but also logs
830 messages with priority "warn" or higher (and not filtered
831 otherwise) to syslog facility "user". Messages with priority higher
832 than "error" will be logged with level "error".
833 $AnyEvent::Log::LOG->attach (
835 new AnyEvent::Log::Ctx
836 level => "warn",
837 cap => "error",
838 syslog => "user",
839 );
840 PERL_ANYEVENT_LOG=log=+%syslog:%syslog=warn,cap=error,syslog
842 Write trace messages (only) from AnyEvent::Debug to the default logging
844 target(s).
845 Attach the $AnyEvent::Log::LOG context to the "AnyEvent::Debug"
846 context - this simply circumvents the global filtering for trace
847 messages.
848 my $debug = AnyEvent::Debug->AnyEvent::Log::ctx;
850 $debug->attach ($AnyEvent::Log::LOG);
851 PERL_ANYEVENT_LOG=AnyEvent::Debug=+log
853 This of course works for any package, not just AnyEvent::Debug, but
855 assumes the log level for AnyEvent::Debug hasn't been changed from
856 the default.
857
859 This module uses AnyEvent::IO to actually write log messages (in
860 "log_to_file" and "log_to_path"), so it doesn't block your program when
861 the disk is busy and a non-blocking AnyEvent::IO backend is available.
862
864 Marc Lehmann <schmorp@schmorp.de>
865 http://anyevent.schmorp.de
866perl v5.32.1 2021-01-26 AnyEvent::Log(3)