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 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
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 logging for the current package to errors and higher only
48          AnyEvent::Log::ctx->level ("error");
49
50          # set logging level to suppress anything below "notice"
51          $AnyEvent::Log::FILTER->level ("notice");
52
53          # 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

DESCRIPTION

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

LOGGING LEVELS

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
93       Instead of specifying levels by name you can also specify them by
94       aliases:
95
96          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
107       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
113       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
118       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
122       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
126       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

LOGGING FUNCTIONS

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
135       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
139           For loglevel "fatal", the program will abort.
140
141           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
144           The $msg should not end with "\n", but may if that is convenient
145           for you. Also, multiline messages are handled properly.
146
147           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
152           This function takes care of saving and restoring $! and $@, so you
153           don't have to.
154
155           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
161           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
167           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
171           Example: log something at error level.
172
173              AE::log error => "something";
174
175           Example: use printf-formatting.
176
177              AE::log info => "%5d %-10.10s %s", $index, $category, $msg;
178
179           Example: only generate a costly dump when the message is actually
180           being logged.
181
182              AE::log debug => sub { require Data::Dump; Data::Dump::dump \%cache };
183
184       $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
190              my $debug_log = AnyEvent::Log::logger "debug";
191
192              $debug_log->("debug here");
193              $debug_log->("%06d emails processed", 12345);
194              $debug_log->(sub { $obj->as_string });
195
196           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
201           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
205           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
210           Full example:
211
212              # near the init section
213              use AnyEvent::Log;
214
215              my $debug_log = AnyEvent:Log::logger debug => \my $debug;
216
217              # and later in your program
218              $debug_log->("yo, stuff here") if $debug;
219
220              $debug and $debug_log->("123");
221
222       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
230           This setting can be changed at any time by calling this function.
231
232           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
237       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
242           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
246           Most commonly, this function can be used in formatting callbacks.
247
248       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
252           This is the formatting function used to format messages when no
253           custom function is provided.
254
255           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
259       AnyEvent::Log::fatal_exit
260           This is the function that is called after logging a "fatal" log
261           message. It must not return.
262
263           The default implementation simply calls "exit 1".
264
265           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

LOGGING CONTEXTS

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
274       A logging context has three major responsibilities: filtering, logging
275       and propagating the message.
276
277       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
281       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
288       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
293       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
297   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
302       Package contexts have the package name as logging title by default.
303
304       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
312       Since perl packages form only an approximate hierarchy, this slave
313       context can of course be removed.
314
315       All other (anonymous) contexts have no slaves and an empty title by
316       default.
317
318       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
324       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
330       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
335       The hierarchy is then:
336
337          any package, eventually -> $COLLECT -> $FILTER -> $LOG
338
339       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
345       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
351       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
355   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
360           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
365           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
369       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
375           This can be used to implement config-file (re-)loading: before
376           loading a configuration, reset all contexts.
377
378       $ctx = new AnyEvent::Log::Ctx methodname => param...
379           This is a convenience constructor that makes it simpler to
380           construct anonymous logging contexts.
381
382           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
388           Example: create a new logging context and set both the default
389           logging level, some slave contexts and a logging callback.
390
391              $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
398   CONFIGURING A LOG CONTEXT
399       The following methods can be used to configure the logging context.
400
401       $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
406           If $new_title is given, then it replaces the package name or title.
407
408       LOGGING LEVELS
409
410       The following methods deal with the logging level set associated with
411       the log context.
412
413       The most common method to use is probably "$ctx->level ($level)", which
414       configures the specified and any higher priority levels.
415
416       All functions which accept a list of levels also accept the special
417       string "all" which expands to all logging levels.
418
419       $ctx->levels ($level[, $level...)
420           Enables logging for the given levels and disables it for all
421           others.
422
423       $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
428           Example: log warnings, errors and higher priority messages.
429
430              $ctx->level ("warn");
431              $ctx->level (5); # same thing, just numeric
432
433       $ctx->enable ($level[, $level...])
434           Enables logging for the given levels, leaving all others unchanged.
435
436       $ctx->disable ($level[, $level...])
437           Disables logging for the given levels, leaving all others
438           unchanged.
439
440       $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
448           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
452           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
459           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
464       SLAVE CONTEXTS
465
466       The following methods attach and detach another logging context to a
467       logging context.
468
469       Log messages are propagated to all slave contexts, unless the logging
470       callback consumes the message.
471
472       $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
476           A context can be specified either as package name or as a context
477           object.
478
479       $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
483           A context can be specified either as package name or as a context
484           object.
485
486       $ctx->slaves ($ctx2[, $ctx3...])
487           Replaces all slaves attached to this context by the ones given.
488
489       LOG TARGETS
490
491       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
495       $ctx->log_cb ($cb->($str))
496           Replaces the logging callback on the context ("undef" disables the
497           logging callback).
498
499           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
503           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
508           Example: a very simple logging callback, simply dump the message to
509           STDOUT and do not consume it.
510
511              $ctx->log_cb (sub { print STDERR shift; 0 });
512
513           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
517           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
521              $ctx->levels ("debug", "trace");
522              $ctx->log_cb (sub { 1 }); # do not log, but eat debug and trace messages
523
524       $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
528           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
534           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
538           To implement your own logging callback, you might find the
539           "AnyEvent::Log::format_time" and "AnyEvent::Log::default_format"
540           functions useful.
541
542           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
547              $ctx->fmt_cb (sub {
548                 my ($time, $ctx, $lvl, $msg) = @_;
549
550                 AnyEvent::Log::default_format $time, $ctx, $lvl, $msg
551              });
552
553           Example: format just the raw message, with numeric log level in
554           angle brackets.
555
556              $ctx->fmt_cb (sub {
557                 my ($time, $ctx, $lvl, $msg) = @_;
558
559                 "<$lvl>$msg\n"
560              });
561
562           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
565              $ctx->fmt_cb (sub { \@_ });
566              $ctx->log_cb (sub {
567                 my ($msg) = @_;
568
569                 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
575                 0
576              });
577
578       $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
582       $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
587       $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
592           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
596       $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
602           Note that this function also sets a "fmt_cb" - the logging part
603           requires an array reference with [$level, $str] as input.
604
605       MESSAGE LOGGING
606
607       These methods allow you to log messages directly to a context, without
608       going via your package context.
609
610       $ctx->log ($level, $msg[, @params])
611           Same as "AnyEvent::Log::log", but uses the given context as log
612           context.
613
614           Example: log a message in the context of another package.
615
616              (AnyEvent::Log::ctx "Other::Package")->log (warn => "heely bo");
617
618       $logger = $ctx->logger ($level[, \$enabled])
619           Same as "AnyEvent::Log::logger", but uses the given context as log
620           context.
621

CONFIGURATION VIA $ENV{PERL_ANYEVENT_LOG}

623       Logging can also be configured by setting the environment variable
624       "PERL_ANYEVENT_LOG" (or "AE_LOG").
625
626       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
631          # set default logging level
632          filter=warn
633
634          # log to file instead of to stderr
635          log=file=/tmp/mylog
636
637          # log to file in addition to stderr
638          log=+%file:%file=file=/tmp/mylog
639
640          # enable debug log messages, log warnings and above to syslog
641          filter=debug:log=+%warnings:%warnings=warn,syslog=LOG_LOCAL0
642
643          # log trace messages (only) from AnyEvent::Debug to file
644          AnyEvent::Debug=+%trace:%trace=only,trace,file=/tmp/tracelog
645
646       A context name in the log specification can be any of the following:
647
648       "collect", "filter", "log"
649           Correspond to the three predefined $AnyEvent::Log::COLLECT,
650           "AnyEvent::Log::FILTER" and $AnyEvent::Log::LOG contexts.
651
652       %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
657           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
661       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
668       The configuration specifications can be any number of the following:
669
670       "stderr"
671           Configures the context to use Perl's "warn" function (which
672           typically logs to "STDERR"). Works like "log_to_warn".
673
674       "file="path
675           Configures the context to log to a file with the given path. Works
676           like "log_to_file".
677
678       "path="path
679           Configures the context to log to a file with the given path. Works
680           like "log_to_path".
681
682       "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
686              log=syslog=LOG_LOCAL0
687
688       "nolog"
689           Configures the context to not log anything by itself, which is the
690           default. Same as "$ctx->log_cb (undef)".
691
692       "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
698       0 or "off"
699           Sets the logging level of the context to 0, i.e. all messages will
700           be filtered out.
701
702       "all"
703           Enables all logging levels, i.e. filtering will effectively be
704           switched off (the default).
705
706       "only"
707           Disables all logging levels, and changes the interpretation of
708           following level specifications to enable the specified level only.
709
710           Example: only enable debug messages for a context.
711
712              context=only,debug
713
714       "except"
715           Enables all logging levels, and changes the interpretation of
716           following level specifications to disable that level. Rarely used.
717
718           Example: enable all logging levels except fatal and trace (this is
719           rather nonsensical).
720
721              filter=exept,fatal,trace
722
723       "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
728           Example: log anything at or above warn level.
729
730              filter=warn
731
732              # or, more verbose
733              filter=only,level,warn
734
735       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
741       "+"context
742           Attaches the named context as slave to the context.
743
744       "+" 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
749           Example: log messages from My::Module to a file, do not send them
750           to the default log collector.
751
752              My::Module=+,file=/tmp/mymodulelog
753
754       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
758          PERL_ANYEVENT_LOG='log=file=/some\ \:file\ with\,\ \\-escapes'
759
760       Since whitespace (which includes newlines) is allowed, it is fine to
761       specify multiple lines in "PERL_ANYEVENT_LOG", e.g.:
762
763          PERL_ANYEVENT_LOG="
764             filter=warn
765             AnyEvent::Debug=+%trace
766             %trace=only,trace,+log
767          " myprog
768
769       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
773          PERL_ANYEVENT_LOG="$PERL_ANYEVENT_LOG MyMod=debug"
774

EXAMPLES

776       This section shows some common configurations, both as code, and as
777       "PERL_ANYEVENT_LOG" string.
778
779       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
784              PERL_ANYEVENT_VERBOSE=5 ./myprog
785
786              PERL_ANYEVENT_LOG=log=warn
787
788              $AnyEvent::Log::FILTER->level ("warn");
789
790       Append all messages to a file instead of sending them to STDERR.
791           This is affected by the global logging level.
792
793              $AnyEvent::Log::LOG->log_to_file ($path);
794
795              PERL_ANYEVENT_LOG=log=file=/some/path
796
797       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
802              $AnyEvent::Log::FILTER->attach (
803                 new AnyEvent::Log::Ctx log_to_file => $path);
804
805              PERL_ANYEVENT_LOG=filter=+%filelogger:%filelogger=file=/some/path
806
807           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
811              $AnyEvent::Log::COLLECT->attach (
812                 new AnyEvent::Log::Ctx log_to_file => $path);
813
814              PERL_ANYEVENT_LOG=%filelogger=file=/some/path:collect=+%filelogger
815
816           In both cases, messages are still written to STDERR.
817
818       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
825              $AnyEvent::Log::LOG->attach (
826                 new AnyEvent::Log::Ctx
827                    level  => "warn",
828                    cap    => "error",
829                    syslog => "user",
830              );
831
832              PERL_ANYEVENT_LOG=log=+%syslog:%syslog=warn,cap=error,syslog
833
834       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
840              my $debug = AnyEvent::Debug->AnyEvent::Log::ctx;
841              $debug->attach ($AnyEvent::Log::LOG);
842
843              PERL_ANYEVENT_LOG=AnyEvent::Debug=+log
844
845           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

ASYNCHRONOUS DISK I/O

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

AUTHOR

855        Marc Lehmann <schmorp@schmorp.de>
856        http://anyevent.schmorp.de
857
858
859
860perl v5.28.0                      2016-03-13                  AnyEvent::Log(3)
Impressum