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.37 by root, Thu Aug 25 06:34:11 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
… …
249 # now get raw message, unless we have it already 252 # now get raw message, unless we have it already
250 unless ($now) { 253 unless ($now) {
251 $format = $format->() if ref $format; 254 $format = $format->() if ref $format;
252 $format = sprintf $format, @args if @args; 255 $format = sprintf $format, @args if @args;
253 $format =~ s/\n$//; 256 $format =~ s/\n$//;
254 $now = AE::now; 257 $now = now;
255 }; 258 };
256 259
257 # format msg 260 # format msg
258 my $str = $ctx->[4] 261 my $str = $ctx->[4]
259 ? $ctx->[4]($now, $_[0], $level, $format) 262 ? $ctx->[4]($now, $_[0], $level, $format)
… …
354 357
355 $LOGGER{$logger+0} = $logger; 358 $LOGGER{$logger+0} = $logger;
356 359
357 _reassess $logger+0; 360 _reassess $logger+0;
358 361
362 require AnyEvent::Util;
359 my $guard = AnyEvent::Util::guard { 363 my $guard = AnyEvent::Util::guard (sub {
360 # "clean up" 364 # "clean up"
361 delete $LOGGER{$logger+0}; 365 delete $LOGGER{$logger+0};
362 }; 366 });
363 367
364 sub { 368 sub {
365 $guard if 0; # keep guard alive, but don't cause runtime overhead 369 $guard if 0; # keep guard alive, but don't cause runtime overhead
366 370
367 _log $ctx, $level, @_ 371 _log $ctx, $level, @_
… …
513 } 517 }
514 518
515 @$_ = ($_->[0], (1 << 10) - 1 - 1) 519 @$_ = ($_->[0], (1 << 10) - 1 - 1)
516 for $LOG, $FILTER, $COLLECT; 520 for $LOG, $FILTER, $COLLECT;
517 521
518 $LOG->slaves; 522 #$LOG->slaves;
519 $LOG->title ('$AnyEvent::Log::LOG'); 523 $LOG->title ('$AnyEvent::Log::LOG');
520 $LOG->log_to_warn; 524 $LOG->log_to_warn;
521 525
522 $FILTER->slaves ($LOG); 526 $FILTER->slaves ($LOG);
523 $FILTER->title ('$AnyEvent::Log::FILTER'); 527 $FILTER->title ('$AnyEvent::Log::FILTER');
… …
1012Configures the context to log to a file with the given path. Works like 1016Configures the context to log to a file with the given path. Works like
1013C<log_to_path>. 1017C<log_to_path>.
1014 1018
1015=item C<syslog> or C<syslog=>I<expr> 1019=item C<syslog> or C<syslog=>I<expr>
1016 1020
1017Configured the context to log to syslog. If I<expr> is given, then it is 1021Configures 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: 1022evaluated in the L<Sys::Syslog> package, so you could use:
1019 1023
1020 log=syslog=LOG_LOCAL0 1024 log=syslog=LOG_LOCAL0
1021 1025
1022=item C<nolog> 1026=item C<nolog>
… …
1064 filter=warn 1068 filter=warn
1065 1069
1066 # or, more verbose 1070 # or, more verbose
1067 filter=only,level,warn 1071 filter=only,level,warn
1068 1072
1069=item C<1>..C<9>, a logging level name (C<error>, C<debug> etc.) 1073=item C<1>..C<9> or a logging level name (C<error>, C<debug> etc.)
1070 1074
1071A numeric loglevel or the name of a loglevel will be interpreted according 1075A 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, 1076to the most recent C<only>, C<except> or C<level> directive. By default,
1073specifying a logging level enables that and any higher priority messages. 1077specifying a logging level enables that and any higher priority messages.
1074 1078
1075=item C<+>I<context> 1079=item C<+>I<context>
1076 1080
1077Adds/attaches the named context as slave to the context. 1081Attaches the named context as slave to the context.
1078 1082
1079=item C<+> 1083=item C<+>
1080 1084
1081A line C<+> clears the slave list form the context. Anonymous (C<%name>) 1085A 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 1086context. Anonymous (C<%name>) contexts have no attached slaves by default,
1083context as slave by default. 1087but package contexts have the parent context as slave by default.
1084 1088
1085Example: log messages from My::Module to a file, do not send them to the 1089Example: log messages from My::Module to a file, do not send them to the
1086default log collector. 1090default log collector.
1087 1091
1088 My::Module=+,file=/tmp/mymodulelog 1092 My::Module=+,file=/tmp/mymodulelog
1089 1093
1090=back 1094=back
1091 1095
1096Any character can be escaped by prefixing it with a C<\> (backslash), as
1097usual, so to log to a file containing a comma, colon, backslash and some
1098spaces in the filename, you would do this:
1099
1100 PERL_ANYEVENT_LOG='log=file=/some\ \:file\ with\,\ \\-escapes'
1101
1102Since whitespace (which includes newlines) is allowed, it is fine to
1103specify multiple lines in C<PERL_ANYEVENT_LOG>, e.g.:
1104
1105 PERL_ANYEVENT_LOG="
1106 filter=warn
1107 AnyEvent::Debug=+%trace
1108 %trace=only,trace,+log
1109 " myprog
1110
1111Also, in the unlikely case when you want to concatenate specifications,
1112use whitespace as separator, as C<::> will be interpreted as part of a
1113module name, an empty spec with two separators:
1114
1115 PERL_ANYEVENT_LOG="$PERL_ANYEVENT_LOG MyMod=debug"
1116
1092=cut 1117=cut
1093 1118
1094for (my $spec = $ENV{PERL_ANYEVENT_LOG}) { 1119for (my $spec = $ENV{PERL_ANYEVENT_LOG}) {
1095 my %anon; 1120 my %anon;
1096 1121
1097 my $pkg = sub { 1122 my $pkg = sub {
1098 $_[0] eq "log" ? $LOG 1123 $_[0] eq "log" ? $LOG
1099 : $_[0] eq "filter" ? $FILTER 1124 : $_[0] eq "filter" ? $FILTER
1100 : $_[0] eq "collect" ? $COLLECT 1125 : $_[0] eq "collect" ? $COLLECT
1101 : $_[0] =~ /^%(.+)$/ && $anon{$1} ||= ctx undef 1126 : $_[0] =~ /^%(.+)$/ ? ($anon{$1} ||= ctx undef)
1102 : $_[0] =~ /^(.*?)(?:::)?$/ && ctx "$1" # egad :/ 1127 : $_[0] =~ /^(.*?)(?:::)?$/ ? ctx "$1" # egad :/
1128 : die # never reached?
1103 }; 1129 };
1104 1130
1131 /\G[[:space:]]+/gc; # skip initial whitespace
1132
1105 while (/\G((?:[^:=]+|::|\\.)+)=/gc) { 1133 while (/\G((?:[^:=[:space:]]+|::|\\.)+)=/gc) {
1106 my $ctx = $pkg->($1); 1134 my $ctx = $pkg->($1);
1107 my $level = "level"; 1135 my $level = "level";
1108 1136
1109 while (/\G((?:[^,:[:space:]]+|::|\\.)+)/gc) { 1137 while (/\G((?:[^,:[:space:]]+|::|\\.)+)/gc) {
1110 for ("$1") { 1138 for ("$1") {
… …
1127 } 1155 }
1128 1156
1129 /\G,/gc or last; 1157 /\G,/gc or last;
1130 } 1158 }
1131 1159
1132 /\G[:[:space:]]/gc or last; 1160 /\G[:[:space:]]+/gc or last;
1133 } 1161 }
1162
1163 /\G[[:space:]]+/gc; # skip trailing whitespace
1134 1164
1135 if (/\G(.+)/g) { 1165 if (/\G(.+)/g) {
1136 die "PERL_ANYEVENT_LOG ($spec): parse error at '$1'\n"; 1166 die "PERL_ANYEVENT_LOG ($spec): parse error at '$1'\n";
1137 } 1167 }
1138} 1168}
1139 1169
11401; 11701;
1141 1171
1142=head1 EXAMPLES 1172=head1 EXAMPLES
1143 1173
1144This section shows some common configurations. 1174This section shows some common configurations, both as code, and as
1175C<PERL_ANYEVENT_LOG> string.
1145 1176
1146=over 4 1177=over 4
1147 1178
1148=item Setting the global logging level. 1179=item Setting the global logging level.
1149 1180
1150Either put PERL_ANYEVENT_VERBOSE=<number> into your environment before 1181Either put C<PERL_ANYEVENT_VERBOSE=><number> into your environment before
1151running your program, or modify the log level of the root context: 1182running your program, use C<PERL_ANYEVENT_LOG> or modify the log level of
1183the root context at runtime:
1152 1184
1153 PERL_ANYEVENT_VERBOSE=5 ./myprog 1185 PERL_ANYEVENT_VERBOSE=5 ./myprog
1154 1186
1187 PERL_ANYEVENT_LOG=log=warn
1188
1155 $AnyEvent::Log::FILTER->level ("warn"); 1189 $AnyEvent::Log::FILTER->level ("warn");
1156 1190
1157=item Append all messages to a file instead of sending them to STDERR. 1191=item Append all messages to a file instead of sending them to STDERR.
1158 1192
1159This is affected by the global logging level. 1193This is affected by the global logging level.
1160 1194
1161 $AnyEvent::Log::LOG->log_to_file ($path); (sub { 1195 $AnyEvent::Log::LOG->log_to_file ($path);
1196
1197 PERL_ANYEVENT_LOG=log=file=/some/path
1162 1198
1163=item Write all messages with priority C<error> and higher to a file. 1199=item Write all messages with priority C<error> and higher to a file.
1164 1200
1165This writes them only when the global logging level allows it, because 1201This writes them only when the global logging level allows it, because
1166it is attached to the default context which is invoked I<after> global 1202it is attached to the default context which is invoked I<after> global
1167filtering. 1203filtering.
1168 1204
1169 $AnyEvent::Log::FILTER->attach 1205 $AnyEvent::Log::FILTER->attach
1170 new AnyEvent::Log::Ctx log_to_file => $path); 1206 new AnyEvent::Log::Ctx log_to_file => $path);
1171 1207
1208 PERL_ANYEVENT_LOG=filter=+%filelogger:%filelogger=file=/some/path
1209
1172This writes them regardless of the global logging level, because it is 1210This writes them regardless of the global logging level, because it is
1173attached to the toplevel context, which receives all messages I<before> 1211attached to the toplevel context, which receives all messages I<before>
1174the global filtering. 1212the global filtering.
1175 1213
1176 $AnyEvent::Log::COLLECT->attach ( 1214 $AnyEvent::Log::COLLECT->attach (
1177 new AnyEvent::Log::Ctx log_to_file => $path); 1215 new AnyEvent::Log::Ctx log_to_file => $path);
1178 1216
1217 PERL_ANYEVENT_LOG=%filelogger=file=/some/path:collect=+%filelogger
1218
1179In both cases, messages are still written to STDERR. 1219In both cases, messages are still written to STDERR.
1180 1220
1181=item Write trace messages (only) from L<AnyEvent::Debug> to the default logging target(s). 1221=item Write trace messages (only) from L<AnyEvent::Debug> to the default logging target(s).
1182 1222
1183Attach the C<$AnyEvent::Log::LOG> context to the C<AnyEvent::Debug> 1223Attach the C<$AnyEvent::Log::LOG> context to the C<AnyEvent::Debug>
1184context - this simply circumvents the global filtering for trace messages. 1224context - this simply circumvents the global filtering for trace messages.
1185 1225
1186 my $debug = AnyEvent::Debug->AnyEvent::Log::ctx; 1226 my $debug = AnyEvent::Debug->AnyEvent::Log::ctx;
1187 $debug->attach ($AnyEvent::Log::LOG); 1227 $debug->attach ($AnyEvent::Log::LOG);
1228
1229 PERL_ANYEVENT_LOG=AnyEvent::Debug=+log
1188 1230
1189This of course works for any package, not just L<AnyEvent::Debug>, but 1231This 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 1232assumes the log level for AnyEvent::Debug hasn't been changed from the
1191default. 1233default.
1192 1234
… …
1196 1238
1197 Marc Lehmann <schmorp@schmorp.de> 1239 Marc Lehmann <schmorp@schmorp.de>
1198 http://home.schmorp.de/ 1240 http://home.schmorp.de/
1199 1241
1200=cut 1242=cut
1243

Diff Legend

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