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.27 by root, Wed Aug 24 23:59:10 2011 UTC vs.
Revision 1.39 by root, Fri Aug 26 00:37:26 2011 UTC

… …
49will be logged, unless you set C<PERL_ANYEVENT_VERBOSE> to a higher number 49will be logged, unless you set C<PERL_ANYEVENT_VERBOSE> to a higher number
50before starting your program, or change the logging level at runtime with 50before starting your program, or change the logging level at runtime with
51something like: 51something like:
52 52
53 use AnyEvent::Log; 53 use AnyEvent::Log;
54 AnyEvent::Log::FILTER->level ("info"); 54 $AnyEvent::Log::FILTER->level ("info");
55 55
56The design goal behind this module was to keep it simple (and small), 56The design goal behind this module was to keep it simple (and small),
57but make it powerful enough to be potentially useful for any module, and 57but make it powerful enough to be potentially useful for any module, and
58extensive enough for the most common tasks, such as logging to multiple 58extensive enough for the most common tasks, such as logging to multiple
59targets, or being able to log into a database. 59targets, or being able to log into a database.
60 60
61The module is also usable before AnyEvent itself is initialised, in which
62case some of the functionality might be reduced.
63
61The amount of documentation might indicate otherwise, but the module is 64The amount of documentation might indicate otherwise, but the runtime part
62still just below 300 lines of code. 65of the module is still just below 300 lines of code.
63 66
64=head1 LOGGING LEVELS 67=head1 LOGGING LEVELS
65 68
66Logging levels in this module range from C<1> (highest priority) to C<9> 69Logging levels in this module range from C<1> (highest priority) to C<9>
67(lowest priority). Note that the lowest numerical value is the highest 70(lowest priority). Note that the lowest numerical value is the highest
… …
108 111
109use Carp (); 112use Carp ();
110use POSIX (); 113use POSIX ();
111 114
112use AnyEvent (); BEGIN { AnyEvent::common_sense } 115use AnyEvent (); BEGIN { AnyEvent::common_sense }
113use AnyEvent::Util (); 116#use AnyEvent::Util (); need to load this in a delayed fashion, as it uses AE::log
114 117
115our $VERSION = $AnyEvent::VERSION; 118our $VERSION = $AnyEvent::VERSION;
116 119
117our ($COLLECT, $FILTER, $LOG); 120our ($COLLECT, $FILTER, $LOG);
118 121
… …
203 info => 7, 206 info => 7,
204 debug => 8, 207 debug => 8,
205 trace => 9, 208 trace => 9,
206); 209);
207 210
208sub now () { time } 211our $TIME_EXACT;
212
213sub exact_time($) {
214 $TIME_EXACT = shift;
215 *_ts = $AnyEvent::MODEL
216 ? $TIME_EXACT ? \&AE::now : \&AE::time
217 : sub () { $TIME_EXACT ? do { require Time::HiRes; Time::HiRes::time () } : time };
218}
219
220BEGIN {
221 exact_time 0;
222}
209 223
210AnyEvent::post_detect { 224AnyEvent::post_detect {
211 *now = \&AE::now; 225 exact_time $TIME_EXACT;
212}; 226};
213 227
214our @LEVEL2STR = qw(0 fatal alert crit error warn note info debug trace); 228our @LEVEL2STR = qw(0 fatal alert crit error warn note info debug trace);
215 229
216# time, ctx, level, msg 230# time, ctx, level, msg
… …
249 # now get raw message, unless we have it already 263 # now get raw message, unless we have it already
250 unless ($now) { 264 unless ($now) {
251 $format = $format->() if ref $format; 265 $format = $format->() if ref $format;
252 $format = sprintf $format, @args if @args; 266 $format = sprintf $format, @args if @args;
253 $format =~ s/\n$//; 267 $format =~ s/\n$//;
254 $now = AE::now; 268 $now = _ts;
255 }; 269 };
256 270
257 # format msg 271 # format msg
258 my $str = $ctx->[4] 272 my $str = $ctx->[4]
259 ? $ctx->[4]($now, $_[0], $level, $format) 273 ? $ctx->[4]($now, $_[0], $level, $format)
… …
354 368
355 $LOGGER{$logger+0} = $logger; 369 $LOGGER{$logger+0} = $logger;
356 370
357 _reassess $logger+0; 371 _reassess $logger+0;
358 372
373 require AnyEvent::Util;
359 my $guard = AnyEvent::Util::guard { 374 my $guard = AnyEvent::Util::guard (sub {
360 # "clean up" 375 # "clean up"
361 delete $LOGGER{$logger+0}; 376 delete $LOGGER{$logger+0};
362 }; 377 });
363 378
364 sub { 379 sub {
365 $guard if 0; # keep guard alive, but don't cause runtime overhead 380 $guard if 0; # keep guard alive, but don't cause runtime overhead
366 381
367 _log $ctx, $level, @_ 382 _log $ctx, $level, @_
… …
372sub logger($;$) { 387sub logger($;$) {
373 _logger 388 _logger
374 $CTX{ (caller)[0] } ||= _pkg_ctx +(caller)[0], 389 $CTX{ (caller)[0] } ||= _pkg_ctx +(caller)[0],
375 @_ 390 @_
376} 391}
392
393=item AnyEvent::Log::exact_time $on
394
395By default, C<AnyEvent::Log> will use C<AE::now>, i.e. the cached
396eventloop time, for the log timestamps. After calling this function with a
397true value it will instead resort to C<AE::time>, i.e. fetch the current
398time on each log message. This only makes a difference for event loops
399that actually cache the time (such as L<EV> or L<AnyEvent::Loop>).
400
401This setting can be changed at any time by calling this function.
402
403Since C<AnyEvent::Log> has to work even before the L<AnyEvent> has been
404initialised, this switch will also decide whether to use C<CORE::time> or
405C<Time::HiRes::time> when logging a message before L<AnyEvent> becomes
406available.
377 407
378=back 408=back
379 409
380=head1 LOGGING CONTEXTS 410=head1 LOGGING CONTEXTS
381 411
… …
513 } 543 }
514 544
515 @$_ = ($_->[0], (1 << 10) - 1 - 1) 545 @$_ = ($_->[0], (1 << 10) - 1 - 1)
516 for $LOG, $FILTER, $COLLECT; 546 for $LOG, $FILTER, $COLLECT;
517 547
518 $LOG->slaves; 548 #$LOG->slaves;
519 $LOG->title ('$AnyEvent::Log::LOG'); 549 $LOG->title ('$AnyEvent::Log::LOG');
520 $LOG->log_to_warn; 550 $LOG->log_to_warn;
521 551
522 $FILTER->slaves ($LOG); 552 $FILTER->slaves ($LOG);
523 $FILTER->title ('$AnyEvent::Log::FILTER'); 553 $FILTER->title ('$AnyEvent::Log::FILTER');
… …
1012Configures the context to log to a file with the given path. Works like 1042Configures the context to log to a file with the given path. Works like
1013C<log_to_path>. 1043C<log_to_path>.
1014 1044
1015=item C<syslog> or C<syslog=>I<expr> 1045=item C<syslog> or C<syslog=>I<expr>
1016 1046
1017Configured the context to log to syslog. If I<expr> is given, then it is 1047Configures the context to log to syslog. If I<expr> is given, then it is
1018evaluated in the L<Sys::Syslog> package, so you could use: 1048evaluated in the L<Sys::Syslog> package, so you could use:
1019 1049
1020 log=syslog=LOG_LOCAL0 1050 log=syslog=LOG_LOCAL0
1021 1051
1022=item C<nolog> 1052=item C<nolog>
… …
1064 filter=warn 1094 filter=warn
1065 1095
1066 # or, more verbose 1096 # or, more verbose
1067 filter=only,level,warn 1097 filter=only,level,warn
1068 1098
1069=item C<1>..C<9>, a logging level name (C<error>, C<debug> etc.) 1099=item C<1>..C<9> or a logging level name (C<error>, C<debug> etc.)
1070 1100
1071A numeric loglevel or the name of a loglevel will be interpreted according 1101A numeric loglevel or the name of a loglevel will be interpreted according
1072to the most recent C<only>, C<except> or C<level> directive. By default, 1102to the most recent C<only>, C<except> or C<level> directive. By default,
1073specifying a logging level enables that and any higher priority messages. 1103specifying a logging level enables that and any higher priority messages.
1074 1104
1075=item C<+>I<context> 1105=item C<+>I<context>
1076 1106
1077Adds/attaches the named context as slave to the context. 1107Attaches the named context as slave to the context.
1078 1108
1079=item C<+> 1109=item C<+>
1080 1110
1081A line C<+> clears the slave list form the context. Anonymous (C<%name>) 1111A line C<+> detaches all contexts, i.e. clears the slave list from the
1082contexts have no slaves by default, but package contexts have the parent 1112context. Anonymous (C<%name>) contexts have no attached slaves by default,
1083context as slave by default. 1113but package contexts have the parent context as slave by default.
1084 1114
1085Example: log messages from My::Module to a file, do not send them to the 1115Example: log messages from My::Module to a file, do not send them to the
1086default log collector. 1116default log collector.
1087 1117
1088 My::Module=+,file=/tmp/mymodulelog 1118 My::Module=+,file=/tmp/mymodulelog
1089 1119
1090=back 1120=back
1091 1121
1122Any character can be escaped by prefixing it with a C<\> (backslash), as
1123usual, so to log to a file containing a comma, colon, backslash and some
1124spaces in the filename, you would do this:
1125
1126 PERL_ANYEVENT_LOG='log=file=/some\ \:file\ with\,\ \\-escapes'
1127
1128Since whitespace (which includes newlines) is allowed, it is fine to
1129specify multiple lines in C<PERL_ANYEVENT_LOG>, e.g.:
1130
1131 PERL_ANYEVENT_LOG="
1132 filter=warn
1133 AnyEvent::Debug=+%trace
1134 %trace=only,trace,+log
1135 " myprog
1136
1137Also, in the unlikely case when you want to concatenate specifications,
1138use whitespace as separator, as C<::> will be interpreted as part of a
1139module name, an empty spec with two separators:
1140
1141 PERL_ANYEVENT_LOG="$PERL_ANYEVENT_LOG MyMod=debug"
1142
1092=cut 1143=cut
1093 1144
1094for (my $spec = $ENV{PERL_ANYEVENT_LOG}) { 1145for (my $spec = $ENV{PERL_ANYEVENT_LOG}) {
1095 my %anon; 1146 my %anon;
1096 1147
1097 my $pkg = sub { 1148 my $pkg = sub {
1098 $_[0] eq "log" ? $LOG 1149 $_[0] eq "log" ? $LOG
1099 : $_[0] eq "filter" ? $FILTER 1150 : $_[0] eq "filter" ? $FILTER
1100 : $_[0] eq "collect" ? $COLLECT 1151 : $_[0] eq "collect" ? $COLLECT
1101 : $_[0] =~ /^%(.+)$/ && $anon{$1} ||= ctx undef 1152 : $_[0] =~ /^%(.+)$/ ? ($anon{$1} ||= ctx undef)
1102 : $_[0] =~ /^(.*?)(?:::)?$/ && ctx "$1" # egad :/ 1153 : $_[0] =~ /^(.*?)(?:::)?$/ ? ctx "$1" # egad :/
1154 : die # never reached?
1103 }; 1155 };
1104 1156
1157 /\G[[:space:]]+/gc; # skip initial whitespace
1158
1105 while (/\G((?:[^:=]+|::|\\.)+)=/gc) { 1159 while (/\G((?:[^:=[:space:]]+|::|\\.)+)=/gc) {
1106 my $ctx = $pkg->($1); 1160 my $ctx = $pkg->($1);
1107 my $level = "level"; 1161 my $level = "level";
1108 1162
1109 while (/\G((?:[^,:[:space:]]+|::|\\.)+)/gc) { 1163 while (/\G((?:[^,:[:space:]]+|::|\\.)+)/gc) {
1110 for ("$1") { 1164 for ("$1") {
… …
1127 } 1181 }
1128 1182
1129 /\G,/gc or last; 1183 /\G,/gc or last;
1130 } 1184 }
1131 1185
1132 /\G[:[:space:]]/gc or last; 1186 /\G[:[:space:]]+/gc or last;
1133 } 1187 }
1188
1189 /\G[[:space:]]+/gc; # skip trailing whitespace
1134 1190
1135 if (/\G(.+)/g) { 1191 if (/\G(.+)/g) {
1136 die "PERL_ANYEVENT_LOG ($spec): parse error at '$1'\n"; 1192 die "PERL_ANYEVENT_LOG ($spec): parse error at '$1'\n";
1137 } 1193 }
1138} 1194}
1139 1195
11401; 11961;
1141 1197
1142=head1 EXAMPLES 1198=head1 EXAMPLES
1143 1199
1144This section shows some common configurations. 1200This section shows some common configurations, both as code, and as
1201C<PERL_ANYEVENT_LOG> string.
1145 1202
1146=over 4 1203=over 4
1147 1204
1148=item Setting the global logging level. 1205=item Setting the global logging level.
1149 1206
1150Either put PERL_ANYEVENT_VERBOSE=<number> into your environment before 1207Either put C<PERL_ANYEVENT_VERBOSE=><number> into your environment before
1151running your program, or modify the log level of the root context: 1208running your program, use C<PERL_ANYEVENT_LOG> or modify the log level of
1209the root context at runtime:
1152 1210
1153 PERL_ANYEVENT_VERBOSE=5 ./myprog 1211 PERL_ANYEVENT_VERBOSE=5 ./myprog
1154 1212
1213 PERL_ANYEVENT_LOG=log=warn
1214
1155 $AnyEvent::Log::FILTER->level ("warn"); 1215 $AnyEvent::Log::FILTER->level ("warn");
1156 1216
1157=item Append all messages to a file instead of sending them to STDERR. 1217=item Append all messages to a file instead of sending them to STDERR.
1158 1218
1159This is affected by the global logging level. 1219This is affected by the global logging level.
1160 1220
1161 $AnyEvent::Log::LOG->log_to_file ($path); (sub { 1221 $AnyEvent::Log::LOG->log_to_file ($path);
1222
1223 PERL_ANYEVENT_LOG=log=file=/some/path
1162 1224
1163=item Write all messages with priority C<error> and higher to a file. 1225=item Write all messages with priority C<error> and higher to a file.
1164 1226
1165This writes them only when the global logging level allows it, because 1227This writes them only when the global logging level allows it, because
1166it is attached to the default context which is invoked I<after> global 1228it is attached to the default context which is invoked I<after> global
1167filtering. 1229filtering.
1168 1230
1169 $AnyEvent::Log::FILTER->attach 1231 $AnyEvent::Log::FILTER->attach
1170 new AnyEvent::Log::Ctx log_to_file => $path); 1232 new AnyEvent::Log::Ctx log_to_file => $path);
1171 1233
1234 PERL_ANYEVENT_LOG=filter=+%filelogger:%filelogger=file=/some/path
1235
1172This writes them regardless of the global logging level, because it is 1236This writes them regardless of the global logging level, because it is
1173attached to the toplevel context, which receives all messages I<before> 1237attached to the toplevel context, which receives all messages I<before>
1174the global filtering. 1238the global filtering.
1175 1239
1176 $AnyEvent::Log::COLLECT->attach ( 1240 $AnyEvent::Log::COLLECT->attach (
1177 new AnyEvent::Log::Ctx log_to_file => $path); 1241 new AnyEvent::Log::Ctx log_to_file => $path);
1178 1242
1243 PERL_ANYEVENT_LOG=%filelogger=file=/some/path:collect=+%filelogger
1244
1179In both cases, messages are still written to STDERR. 1245In both cases, messages are still written to STDERR.
1180 1246
1181=item Write trace messages (only) from L<AnyEvent::Debug> to the default logging target(s). 1247=item Write trace messages (only) from L<AnyEvent::Debug> to the default logging target(s).
1182 1248
1183Attach the C<$AnyEvent::Log::LOG> context to the C<AnyEvent::Debug> 1249Attach the C<$AnyEvent::Log::LOG> context to the C<AnyEvent::Debug>
1184context - this simply circumvents the global filtering for trace messages. 1250context - this simply circumvents the global filtering for trace messages.
1185 1251
1186 my $debug = AnyEvent::Debug->AnyEvent::Log::ctx; 1252 my $debug = AnyEvent::Debug->AnyEvent::Log::ctx;
1187 $debug->attach ($AnyEvent::Log::LOG); 1253 $debug->attach ($AnyEvent::Log::LOG);
1254
1255 PERL_ANYEVENT_LOG=AnyEvent::Debug=+log
1188 1256
1189This of course works for any package, not just L<AnyEvent::Debug>, but 1257This of course works for any package, not just L<AnyEvent::Debug>, but
1190assumes the log level for AnyEvent::Debug hasn't been changed from the 1258assumes the log level for AnyEvent::Debug hasn't been changed from the
1191default. 1259default.
1192 1260
… …
1196 1264
1197 Marc Lehmann <schmorp@schmorp.de> 1265 Marc Lehmann <schmorp@schmorp.de>
1198 http://home.schmorp.de/ 1266 http://home.schmorp.de/
1199 1267
1200=cut 1268=cut
1269

Diff Legend

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