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

NAME

6       AnyEvent::Log - simple logging "framework"
7

SYNOPSIS

9       Simple uses:
10
11          use AnyEvent;
12
13          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
23       Log level overview:
24
25          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
36       "Complex" uses (for speed sensitive code, e.g. trace/debug messages):
37
38          use AnyEvent::Log;
39
40          my $tracer = AnyEvent::Log::logger trace => \my $trace;
41
42          $tracer->("i am here") if $trace;
43          $tracer->(sub { "lots of data: " . Dumper $self }) if $trace;
44
45       Configuration (also look at the EXAMPLES section):
46
47          # 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
52          # set logging for the current package to errors and higher only
53          AnyEvent::Log::ctx->level ("error");
54
55          # enable logging for the current package, regardless of global logging level
56          AnyEvent::Log::ctx->attach ($AnyEvent::Log::LOG);
57
58          # 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
62          # 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

DESCRIPTION

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
76       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
82          use AnyEvent::Log;
83          $AnyEvent::Log::FILTER->level ("info");
84
85       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
90       The module is also usable before AnyEvent itself is initialised, in
91       which case some of the functionality might be reduced.
92
93       The amount of documentation might indicate otherwise, but the runtime
94       part of the module is still just below 300 lines of code.
95

LOGGING LEVELS

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
102       Instead of specifying levels by name you can also specify them by
103       aliases:
104
105          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
116       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
122       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
127       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
131       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
135       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

LOGGING FUNCTIONS

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
144       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
148           For loglevel "fatal", the program will abort.
149
150           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
153           The $msg should not end with "\n", but may if that is convenient
154           for you. Also, multiline messages are handled properly.
155
156           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
161           This function takes care of saving and restoring $! and $@, so you
162           don't have to.
163
164           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
170           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
176           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
180           Example: log something at error level.
181
182              AE::log error => "something";
183
184           Example: use printf-formatting.
185
186              AE::log info => "%5d %-10.10s %s", $index, $category, $msg;
187
188           Example: only generate a costly dump when the message is actually
189           being logged.
190
191              AE::log debug => sub { require Data::Dump; Data::Dump::dump \%cache };
192
193       $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
199              my $debug_log = AnyEvent::Log::logger "debug";
200
201              $debug_log->("debug here");
202              $debug_log->("%06d emails processed", 12345);
203              $debug_log->(sub { $obj->as_string });
204
205           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
210           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
214           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
219           Full example:
220
221              # near the init section
222              use AnyEvent::Log;
223
224              my $debug_log = AnyEvent:Log::logger debug => \my $debug;
225
226              # and later in your program
227              $debug_log->("yo, stuff here") if $debug;
228
229              $debug and $debug_log->("123");
230
231       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
239           This setting can be changed at any time by calling this function.
240
241           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
246       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
251           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
255           Most commonly, this function can be used in formatting callbacks.
256
257       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
261           This is the formatting function used to format messages when no
262           custom function is provided.
263
264           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
268       AnyEvent::Log::fatal_exit()
269           This is the function that is called after logging a "fatal" log
270           message. It must not return.
271
272           The default implementation simply calls "exit 1".
273
274           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

LOGGING CONTEXTS

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
283       A logging context has three major responsibilities: filtering, logging
284       and propagating the message.
285
286       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
290       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
297       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
302       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
306   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
311       Package contexts have the package name as logging title by default.
312
313       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
321       Since perl packages form only an approximate hierarchy, this slave
322       context can of course be removed.
323
324       All other (anonymous) contexts have no slaves and an empty title by
325       default.
326
327       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
333       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
339       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
344       The hierarchy is then:
345
346          any package, eventually -> $COLLECT -> $FILTER -> $LOG
347
348       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
354       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
360       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
364   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
369           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
374           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
378       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
384           This can be used to implement config-file (re-)loading: before
385           loading a configuration, reset all contexts.
386
387       $ctx = new AnyEvent::Log::Ctx methodname => param...
388           This is a convenience constructor that makes it simpler to
389           construct anonymous logging contexts.
390
391           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
397           Example: create a new logging context and set both the default
398           logging level, some slave contexts and a logging callback.
399
400              $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
407   CONFIGURING A LOG CONTEXT
408       The following methods can be used to configure the logging context.
409
410       $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
415           If $new_title is given, then it replaces the package name or title.
416
417       LOGGING LEVELS
418
419       The following methods deal with the logging level set associated with
420       the log context.
421
422       The most common method to use is probably "$ctx->level ($level)", which
423       configures the specified and any higher priority levels.
424
425       All functions which accept a list of levels also accept the special
426       string "all" which expands to all logging levels.
427
428       $ctx->levels ($level[, $level...)
429           Enables logging for the given levels and disables it for all
430           others.
431
432       $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
437           Example: log warnings, errors and higher priority messages.
438
439              $ctx->level ("warn");
440              $ctx->level (5); # same thing, just numeric
441
442       $ctx->enable ($level[, $level...])
443           Enables logging for the given levels, leaving all others unchanged.
444
445       $ctx->disable ($level[, $level...])
446           Disables logging for the given levels, leaving all others
447           unchanged.
448
449       $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
457           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
461           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
468           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
473       SLAVE CONTEXTS
474
475       The following methods attach and detach another logging context to a
476       logging context.
477
478       Log messages are propagated to all slave contexts, unless the logging
479       callback consumes the message.
480
481       $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
485           A context can be specified either as package name or as a context
486           object.
487
488       $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
492           A context can be specified either as package name or as a context
493           object.
494
495       $ctx->slaves ($ctx2[, $ctx3...])
496           Replaces all slaves attached to this context by the ones given.
497
498       LOG TARGETS
499
500       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
504       $ctx->log_cb ($cb->($str))
505           Replaces the logging callback on the context ("undef" disables the
506           logging callback).
507
508           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
512           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
517           Example: a very simple logging callback, simply dump the message to
518           STDOUT and do not consume it.
519
520              $ctx->log_cb (sub { print STDERR shift; 0 });
521
522           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
526           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
530              $ctx->levels ("debug", "trace");
531              $ctx->log_cb (sub { 1 }); # do not log, but eat debug and trace messages
532
533       $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
537           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
543           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
547           To implement your own logging callback, you might find the
548           "AnyEvent::Log::format_time" and "AnyEvent::Log::default_format"
549           functions useful.
550
551           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
556              $ctx->fmt_cb (sub {
557                 my ($time, $ctx, $lvl, $msg) = @_;
558
559                 AnyEvent::Log::default_format $time, $ctx, $lvl, $msg
560              });
561
562           Example: format just the raw message, with numeric log level in
563           angle brackets.
564
565              $ctx->fmt_cb (sub {
566                 my ($time, $ctx, $lvl, $msg) = @_;
567
568                 "<$lvl>$msg\n"
569              });
570
571           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
574              $ctx->fmt_cb (sub { \@_ });
575              $ctx->log_cb (sub {
576                 my ($msg) = @_;
577
578                 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
584                 0
585              });
586
587       $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
591       $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
596       $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
601           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
605       $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
611           Note that this function also sets a "fmt_cb" - the logging part
612           requires an array reference with [$level, $str] as input.
613
614       MESSAGE LOGGING
615
616       These methods allow you to log messages directly to a context, without
617       going via your package context.
618
619       $ctx->log ($level, $msg[, @params])
620           Same as "AnyEvent::Log::log", but uses the given context as log
621           context.
622
623           Example: log a message in the context of another package.
624
625              (AnyEvent::Log::ctx "Other::Package")->log (warn => "heely bo");
626
627       $logger = $ctx->logger ($level[, \$enabled])
628           Same as "AnyEvent::Log::logger", but uses the given context as log
629           context.
630

CONFIGURATION VIA $ENV{PERL_ANYEVENT_LOG}

632       Logging can also be configured by setting the environment variable
633       "PERL_ANYEVENT_LOG" (or "AE_LOG").
634
635       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
640          # set default logging level
641          filter=warn
642
643          # log to file instead of to stderr
644          log=file=/tmp/mylog
645
646          # log to file in addition to stderr
647          log=+%file:%file=file=/tmp/mylog
648
649          # enable debug log messages, log warnings and above to syslog
650          filter=debug:log=+%warnings:%warnings=warn,syslog=LOG_LOCAL0
651
652          # log trace messages (only) from AnyEvent::Debug to file
653          AnyEvent::Debug=+%trace:%trace=only,trace,file=/tmp/tracelog
654
655       A context name in the log specification can be any of the following:
656
657       "collect", "filter", "log"
658           Correspond to the three predefined $AnyEvent::Log::COLLECT,
659           "AnyEvent::Log::FILTER" and $AnyEvent::Log::LOG contexts.
660
661       %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
666           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
670       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
677       The configuration specifications can be any number of the following:
678
679       "stderr"
680           Configures the context to use Perl's "warn" function (which
681           typically logs to "STDERR"). Works like "log_to_warn".
682
683       "file="path
684           Configures the context to log to a file with the given path. Works
685           like "log_to_file".
686
687       "path="path
688           Configures the context to log to a file with the given path. Works
689           like "log_to_path".
690
691       "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
695              log=syslog=LOG_LOCAL0
696
697       "nolog"
698           Configures the context to not log anything by itself, which is the
699           default. Same as "$ctx->log_cb (undef)".
700
701       "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
707       0 or "off"
708           Sets the logging level of the context to 0, i.e. all messages will
709           be filtered out.
710
711       "all"
712           Enables all logging levels, i.e. filtering will effectively be
713           switched off (the default).
714
715       "only"
716           Disables all logging levels, and changes the interpretation of
717           following level specifications to enable the specified level only.
718
719           Example: only enable debug messages for a context.
720
721              context=only,debug
722
723       "except"
724           Enables all logging levels, and changes the interpretation of
725           following level specifications to disable that level. Rarely used.
726
727           Example: enable all logging levels except fatal and trace (this is
728           rather nonsensical).
729
730              filter=exept,fatal,trace
731
732       "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
737           Example: log anything at or above warn level.
738
739              filter=warn
740
741              # or, more verbose
742              filter=only,level,warn
743
744       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
750       "+"context
751           Attaches the named context as slave to the context.
752
753       "+" 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
758           Example: log messages from My::Module to a file, do not send them
759           to the default log collector.
760
761              My::Module=+,file=/tmp/mymodulelog
762
763       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
767          PERL_ANYEVENT_LOG='log=file=/some\ \:file\ with\,\ \\-escapes'
768
769       Since whitespace (which includes newlines) is allowed, it is fine to
770       specify multiple lines in "PERL_ANYEVENT_LOG", e.g.:
771
772          PERL_ANYEVENT_LOG="
773             filter=warn
774             AnyEvent::Debug=+%trace
775             %trace=only,trace,+log
776          " myprog
777
778       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
782          PERL_ANYEVENT_LOG="$PERL_ANYEVENT_LOG MyMod=debug"
783

EXAMPLES

785       This section shows some common configurations, both as code, and as
786       "PERL_ANYEVENT_LOG" string.
787
788       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
793              PERL_ANYEVENT_VERBOSE=5 ./myprog
794
795              PERL_ANYEVENT_LOG=log=warn
796
797              $AnyEvent::Log::FILTER->level ("warn");
798
799       Append all messages to a file instead of sending them to STDERR.
800           This is affected by the global logging level.
801
802              $AnyEvent::Log::LOG->log_to_file ($path);
803
804              PERL_ANYEVENT_LOG=log=file=/some/path
805
806       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
811              $AnyEvent::Log::FILTER->attach (
812                 new AnyEvent::Log::Ctx log_to_file => $path);
813
814              PERL_ANYEVENT_LOG=filter=+%filelogger:%filelogger=file=/some/path
815
816           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
820              $AnyEvent::Log::COLLECT->attach (
821                 new AnyEvent::Log::Ctx log_to_file => $path);
822
823              PERL_ANYEVENT_LOG=%filelogger=file=/some/path:collect=+%filelogger
824
825           In both cases, messages are still written to STDERR.
826
827       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
834              $AnyEvent::Log::LOG->attach (
835                 new AnyEvent::Log::Ctx
836                    level  => "warn",
837                    cap    => "error",
838                    syslog => "user",
839              );
840
841              PERL_ANYEVENT_LOG=log=+%syslog:%syslog=warn,cap=error,syslog
842
843       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
849              my $debug = AnyEvent::Debug->AnyEvent::Log::ctx;
850              $debug->attach ($AnyEvent::Log::LOG);
851
852              PERL_ANYEVENT_LOG=AnyEvent::Debug=+log
853
854           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

ASYNCHRONOUS DISK I/O

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

AUTHOR

864        Marc Lehmann <schmorp@schmorp.de>
865        http://anyevent.schmorp.de
866
867
868
869perl v5.36.0                      2023-01-19                  AnyEvent::Log(3)
Impressum