11
AE::log fatal => "No config found, cannot continue!"; # never returns
12
AE::log alert => "The battery died!";
13
AE::log crit => "The battery temperature is too hot!";
14
AE::log error => "Division by zero attempted.";
15
AE::log warn => "Couldn't delete the file.";
16
AE::log note => "Wanted to create config, but config already exists.";
17
AE::log info => "File soandso successfully deleted.";
18
AE::log debug => "the function returned 3";
11
19
AE::log trace => "going to call function abc";
12
AE::log debug => "the function returned 3";
13
AE::log info => "file soandso successfully deleted";
14
AE::log note => "wanted to create config, but config was alraedy created";
15
AE::log warn => "couldn't delete the file";
16
AE::log error => "failed to retrieve data";
17
AE::log crit => "the battery temperature is too hot";
18
AE::log alert => "the battery died";
19
AE::log fatal => "no config found, cannot continue"; # never returns
21
21
Log level overview:
63
63
module more or less exposes the mechanism, with some extra spiff to allow
64
64
using it from other modules as well.
66
Remember that the default verbosity level is C<0> (C<off>), so nothing
67
will be logged, unless you set C<PERL_ANYEVENT_VERBOSE> to a higher number
68
before starting your program, or change the logging level at runtime with
66
Remember that the default verbosity level is C<4> (C<error>), so only
67
errors and more important messages will be logged, unless you set
68
C<PERL_ANYEVENT_VERBOSE> to a higher number before starting your program
69
(C<AE_VERBOSE=5> is recommended during development), or change the logging
70
level at runtime with something like:
72
73
$AnyEvent::Log::FILTER->level ("info");
108
109
messages at C<error> priority. The NOTE column tries to provide some
109
110
rationale on how to chose a logging level.
111
As a rough guideline, levels 1..3 are primarily meant for users of
112
the program (admins, staff), and are the only logged to STDERR by
112
As a rough guideline, levels 1..3 are primarily meant for users of the
113
program (admins, staff), and are the only ones logged to STDERR by
113
114
default. Levels 4..6 are meant for users and developers alike, while
114
115
levels 7..9 are usually meant for developers.
116
You can normally only log a single message at highest priority level
117
(C<1>, C<fatal>), because logging a fatal message will also quit the
118
program - so use it sparingly :)
117
You can normally only log a message once at highest priority level (C<1>,
118
C<fatal>), because logging a fatal message will also quit the program - so
121
For example, a program that finds an unknown switch on the commandline
122
might well use a fatal logging level to tell users about it - the "system"
123
in this case would be the program, or module.
120
125
Some methods also offer some extra levels, such as C<0>, C<off>, C<none>
121
or C<all> - these are only valid in the methods they are documented for.
126
or C<all> - these are only valid for the methods that documented them.
123
128
=head1 LOGGING FUNCTIONS
125
These functions allow you to log messages. They always use the caller's
126
package as a "logging context". Also, the main logging function C<log> is
127
callable as C<AnyEvent::log> or C<AE::log> when the C<AnyEvent> module is
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 function,
132
C<log>, is aliased to C<AnyEvent::log> and C<AE::log> when the C<AnyEvent>
896
901
default formatter).
898
903
The callback is passed the (possibly fractional) timestamp, the original
899
logging context, the (numeric) logging level and the raw message string
900
and needs to return a formatted log message. In most cases this will be a
901
string, but it could just as well be an array reference that just stores
904
logging context (object, not title), the (numeric) logging level and
905
the raw message string and needs to return a formatted log message. In
906
most cases this will be a string, but it could just as well be an array
907
reference that just stores the values.
904
If, for some reason, you want to use C<caller> to find out more baout the
909
If, for some reason, you want to use C<caller> to find out more about the
905
910
logger then you should walk up the call stack until you are no longer
906
911
inside the C<AnyEvent::Log> package.
917
922
Example: return an array reference with just the log values, and use
918
C<PApp::SQL::sql_exec> to store the emssage in a database.
923
C<PApp::SQL::sql_exec> to store the message in a database.
920
925
$ctx->fmt_cb (sub { \@_ });
921
926
$ctx->log_cb (sub {
938
943
=item $ctx->log_to_file ($path)
940
Sets the C<log_cb> to log to a file (by appending), unbuffered.
945
Sets the C<log_cb> to log to a file (by appending), unbuffered. The
946
function might return before the log file has been opened or created.
942
948
=item $ctx->log_to_path ($path)
991
# this function is a good example of why threads are a must,
992
# simply for priority inversion.
994
# eval'uating this at runtime saves 220kb rss - perl has become
995
# an insane memory waster.
996
eval q{ # poor man's autoloading {}
998
my ($ctx, $path, $keepopen) = @_;
1005
use AnyEvent::IO ();
1009
return unless @queue;
1012
# we pass $kick to $kick, so $kick itself doesn't keep a reference to $kick.
1015
# write one or more messages
1017
# we write as many messages as have been queued
1018
my $data = join "", @queue;
1021
AnyEvent::IO::aio_write $fh, $data, sub {
1024
? ($_[0] == length $data or AE::log 4 => "unable to write to logfile '$path': short write")
1025
: AE::log 4 => "unable to write to logfile '$path': $!";
1031
AnyEvent::IO::aio_close ($fh, sub {
1042
AnyEvent::IO::aio_open
1044
AnyEvent::IO::O_CREAT | AnyEvent::IO::O_WRONLY | AnyEvent::IO::O_APPEND,
1050
AE::log 4 => "unable to open logfile '$path': $!";
1064
$kick->($kick) unless $delay;
1068
$kick->($kick) if $keepopen; # initial open
985
1075
sub log_to_file {
986
1076
my ($ctx, $path) = @_;
988
open my $fh, ">>", $path
1078
_log_to_disk $ctx, $path, 1;
997
1081
sub log_to_path {
998
1082
my ($ctx, $path) = @_;
1001
open my $fh, ">>", $path
1004
syswrite $fh, shift;
1084
_log_to_disk $ctx, $path, 0;
1009
1087
sub log_to_syslog {
1044
1122
Same as C<AnyEvent::Log::log>, but uses the given context as log context.
1124
Example: log a message in the context of another package.
1126
(AnyEvent::Log::ctx "Other::Package")->log (warn => "heely bo");
1046
1128
=item $logger = $ctx->logger ($level[, \$enabled])
1048
1130
Same as C<AnyEvent::Log::logger>, but uses the given context as log
1202
A line C<+> detaches all contexts, i.e. clears the slave list from the
1284
A lone C<+> detaches all contexts, i.e. clears the slave list from the
1203
1285
context. Anonymous (C<%name>) contexts have no attached slaves by default,
1204
1286
but package contexts have the parent context as slave by default.
added
removed
lib/AnyEvent/Log.pm
