ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/AnyEvent/lib/AnyEvent/Log.pm
(Generate patch)

Comparing AnyEvent/lib/AnyEvent/Log.pm (file contents):
Revision 1.45 by root, Sun Oct 2 00:42:04 2011 UTC vs.
Revision 1.49 by root, Thu Mar 22 01:03:57 2012 UTC

… …
9 use AnyEvent; 9 use AnyEvent;
10 10
11 AE::log trace => "going to call function abc"; 11 AE::log trace => "going to call function abc";
12 AE::log debug => "the function returned 3"; 12 AE::log debug => "the function returned 3";
13 AE::log info => "file soandso successfully deleted"; 13 AE::log info => "file soandso successfully deleted";
14 AE::log note => "wanted to create config, but config was alraedy created"; 14 AE::log note => "wanted to create config, but config was already created";
15 AE::log warn => "couldn't delete the file"; 15 AE::log warn => "couldn't delete the file";
16 AE::log error => "failed to retrieve data"; 16 AE::log error => "failed to retrieve data";
17 AE::log crit => "the battery temperature is too hot"; 17 AE::log crit => "the battery temperature is too hot";
18 AE::log alert => "the battery died"; 18 AE::log alert => "the battery died";
19 AE::log fatal => "no config found, cannot continue"; # never returns 19 AE::log fatal => "no config found, cannot continue"; # never returns
… …
61attempt to be "the" logging solution or even "a" logging solution for 61attempt to be "the" logging solution or even "a" logging solution for
62AnyEvent - AnyEvent simply creates logging messages internally, and this 62AnyEvent - AnyEvent simply creates logging messages internally, and this
63module more or less exposes the mechanism, with some extra spiff to allow 63module more or less exposes the mechanism, with some extra spiff to allow
64using it from other modules as well. 64using it from other modules as well.
65 65
66Remember that the default verbosity level is C<0> (C<off>), so nothing 66Remember that the default verbosity level is C<3> (C<critical>), so little
67will be logged, unless you set C<PERL_ANYEVENT_VERBOSE> to a higher number 67will be logged, unless you set C<PERL_ANYEVENT_VERBOSE> to a higher number
68before starting your program, or change the logging level at runtime with 68before starting your program, or change the logging level at runtime with
69something like: 69something like:
70 70
71 use AnyEvent::Log; 71 use AnyEvent::Log;
… …
106is the "official" name, the second one the "syslog" name (if it differs) 106is the "official" name, the second one the "syslog" name (if it differs)
107and the third one the "perl" name, suggesting (only!) that you log C<die> 107and the third one the "perl" name, suggesting (only!) that you log C<die>
108messages at C<error> priority. The NOTE column tries to provide some 108messages at C<error> priority. The NOTE column tries to provide some
109rationale on how to chose a logging level. 109rationale on how to chose a logging level.
110 110
111As a rough guideline, levels 1..3 are primarily meant for users of 111As a rough guideline, levels 1..3 are primarily meant for users of the
112the program (admins, staff), and are the only logged to STDERR by 112program (admins, staff), and are the only ones logged to STDERR by
113default. Levels 4..6 are meant for users and developers alike, while 113default. Levels 4..6 are meant for users and developers alike, while
114levels 7..9 are usually meant for developers. 114levels 7..9 are usually meant for developers.
115 115
116You can normally only log a single message at highest priority level 116You can normally only log a message once at highest priority level (C<1>,
117(C<1>, C<fatal>), because logging a fatal message will also quit the 117C<fatal>), because logging a fatal message will also quit the program - so
118program - so use it sparingly :) 118use it sparingly :)
119 119
120Some methods also offer some extra levels, such as C<0>, C<off>, C<none> 120Some methods also offer some extra levels, such as C<0>, C<off>, C<none>
121or C<all> - these are only valid in the methods they are documented for. 121or C<all> - these are only valid for the methods that documented them.
122 122
123=head1 LOGGING FUNCTIONS 123=head1 LOGGING FUNCTIONS
124 124
125These functions allow you to log messages. They always use the caller's 125The following functions allow you to log messages. They always use the
126package as a "logging context". Also, the main logging function C<log> is 126caller's package as a "logging context". Also, the main logging function,
127callable as C<AnyEvent::log> or C<AE::log> when the C<AnyEvent> module is 127C<log>, is aliased to C<AnyEvent::log> and C<AE::log> when the C<AnyEvent>
128loaded. 128module is loaded.
129 129
130=over 4 130=over 4
131 131
132=cut 132=cut
133 133
… …
191 191
192Last not least, C<$msg> might be a code reference, in which case it is 192Last not least, C<$msg> might be a code reference, in which case it is
193supposed to return the message. It will be called only then the message 193supposed to return the message. It will be called only then the message
194actually gets logged, which is useful if it is costly to create the 194actually gets logged, which is useful if it is costly to create the
195message in the first place. 195message in the first place.
196
197This function takes care of saving and restoring C<$!> and C<$@>, so you
198don't have to.
196 199
197Whether the given message will be logged depends on the maximum log level 200Whether the given message will be logged depends on the maximum log level
198and the caller's package. The return value can be used to ensure that 201and the caller's package. The return value can be used to ensure that
199messages or not "lost" - for example, when L<AnyEvent::Debug> detects a 202messages or not "lost" - for example, when L<AnyEvent::Debug> detects a
200runtime error it tries to log it at C<die> level, but if that message is 203runtime error it tries to log it at C<die> level, but if that message is
… …
301 304
302 # log if log cb 305 # log if log cb
303 if ($ctx->[3]) { 306 if ($ctx->[3]) {
304 # logging target found 307 # logging target found
305 308
309 local ($!, $@);
310
306 # now get raw message, unless we have it already 311 # now get raw message, unless we have it already
307 unless ($now) { 312 unless ($now) {
308 $format = $format->() if ref $format; 313 $format = $format->() if ref $format;
309 $format = sprintf $format, @args if @args; 314 $format = sprintf $format, @args if @args;
310 $format =~ s/\n$//; 315 $format =~ s/\n$//;
… …
894logging context, the (numeric) logging level and the raw message string 899logging context, the (numeric) logging level and the raw message string
895and needs to return a formatted log message. In most cases this will be a 900and needs to return a formatted log message. In most cases this will be a
896string, but it could just as well be an array reference that just stores 901string, but it could just as well be an array reference that just stores
897the values. 902the values.
898 903
899If, for some reason, you want to use C<caller> to find out more baout the 904If, for some reason, you want to use C<caller> to find out more about the
900logger then you should walk up the call stack until you are no longer 905logger then you should walk up the call stack until you are no longer
901inside the C<AnyEvent::Log> package. 906inside the C<AnyEvent::Log> package.
902 907
903Example: format just the raw message, with numeric log level in angle 908Example: format just the raw message, with numeric log level in angle
904brackets. 909brackets.
… …
1192 1197
1193Attaches the named context as slave to the context. 1198Attaches the named context as slave to the context.
1194 1199
1195=item C<+> 1200=item C<+>
1196 1201
1197A line C<+> detaches all contexts, i.e. clears the slave list from the 1202A lone C<+> detaches all contexts, i.e. clears the slave list from the
1198context. Anonymous (C<%name>) contexts have no attached slaves by default, 1203context. Anonymous (C<%name>) contexts have no attached slaves by default,
1199but package contexts have the parent context as slave by default. 1204but package contexts have the parent context as slave by default.
1200 1205
1201Example: log messages from My::Module to a file, do not send them to the 1206Example: log messages from My::Module to a file, do not send them to the
1202default log collector. 1207default log collector.

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines