[ViewVC] Diff of: cvs/AnyEvent/lib/AnyEvent/Log.pm

Comparing AnyEvent/lib/AnyEvent/Log.pm (file contents):
Revision 1.24 by root, Sun Aug 21 03:24:59 2011 UTC vs.
Revision 1.29 by root, Thu Aug 25 00:14:32 2011 UTC

…		…
2		2
3	AnyEvent::Log - simple logging "framework"	3	AnyEvent::Log - simple logging "framework"
4		4
5	=head1 SYNOPSIS	5	=head1 SYNOPSIS
6		6
7	# simple use:	7	Simple uses:
8		8
9	use AnyEvent;	9	use AnyEvent;
10		10
11	AE::log debug => "hit my knee";	11	AE::log debug => "hit my knee";
12	AE::log warn => "it's a bit too hot";	12	AE::log warn => "it's a bit too hot";
13	AE::log error => "the flag was false!";	13	AE::log error => "the flag was false!";
14	AE::log fatal => "the bit toggled! run!"; # never returns	14	AE::log fatal => "the bit toggled! run!"; # never returns
15		15
16	# "complex" use (for speed sensitive code):	16	"Complex" uses (for speed sensitive code):
17		17
18	use AnyEvent::Log;	18	use AnyEvent::Log;
19		19
20	my $tracer = AnyEvent::Log::logger trace => \$my $trace;	20	my $tracer = AnyEvent::Log::logger trace => \$my $trace;
21		21
22	$tracer->("i am here") if $trace;	22	$tracer->("i am here") if $trace;
23	$tracer->(sub { "lots of data: " . Dumper $self }) if $trace;	23	$tracer->(sub { "lots of data: " . Dumper $self }) if $trace;
24		24
25	# configuration:	25	Configuration (also look at the EXAMPLES section):
26		26
27	# set logging for the current package to errors and higher only	27	# set logging for the current package to errors and higher only
28	AnyEvent::Log::ctx->level ("error");	28	AnyEvent::Log::ctx->level ("error");
29		29
30	# set logging level to suppress anything below "notice"	30	# set logging level to suppress anything below "notice"
…		…
34	# regardless of (most) other settings	34	# regardless of (most) other settings
35	$AnyEvent::Log::COLLECT->attach (new AnyEvent::Log::Ctx	35	$AnyEvent::Log::COLLECT->attach (new AnyEvent::Log::Ctx
36	level => "critical",	36	level => "critical",
37	log_to_syslog => 0,	37	log_to_syslog => 0,
38	);	38	);
39
40	# see also EXAMPLES, below
41		39
42	=head1 DESCRIPTION	40	=head1 DESCRIPTION
43		41
44	This module implements a relatively simple "logging framework". It doesn't	42	This module implements a relatively simple "logging framework". It doesn't
45	attempt to be "the" logging solution or even "a" logging solution for	43	attempt to be "the" logging solution or even "a" logging solution for
…		…
517	@$_ = ($_->[0], (1 << 10) - 1 - 1)	515	@$_ = ($_->[0], (1 << 10) - 1 - 1)
518	for $LOG, $FILTER, $COLLECT;	516	for $LOG, $FILTER, $COLLECT;
519		517
520	$LOG->slaves;	518	$LOG->slaves;
521	$LOG->title ('$AnyEvent::Log::LOG');	519	$LOG->title ('$AnyEvent::Log::LOG');
522	$LOG->log_cb (sub {	520	$LOG->log_to_warn;
523	warn shift;
524	0
525	});
526		521
527	$FILTER->slaves ($LOG);	522	$FILTER->slaves ($LOG);
528	$FILTER->title ('$AnyEvent::Log::FILTER');	523	$FILTER->title ('$AnyEvent::Log::FILTER');
529	$FILTER->level ($AnyEvent::VERBOSE);	524	$FILTER->level ($AnyEvent::VERBOSE);
530		525
…		…
791	logging context, the (numeric) logging level and the raw message string	786	logging context, the (numeric) logging level and the raw message string
792	and needs to return a formatted log message. In most cases this will be a	787	and needs to return a formatted log message. In most cases this will be a
793	string, but it could just as well be an array reference that just stores	788	string, but it could just as well be an array reference that just stores
794	the values.	789	the values.
795		790
796	If, for some reaosn, you want to use C<caller> to find out more baout the	791	If, for some reason, you want to use C<caller> to find out more baout the
797	logger then you should walk up the call stack until you are no longer	792	logger then you should walk up the call stack until you are no longer
798	inside the C<AnyEvent::Log> package.	793	inside the C<AnyEvent::Log> package.
799		794
800	Example: format just the raw message, with numeric log level in angle	795	Example: format just the raw message, with numeric log level in angle
801	brackets.	796	brackets.
…		…
820	"$msg->[3]";	815	"$msg->[3]";
821		816
822	0	817	0
823	});	818	});
824		819
		820	=item $ctx->log_to_warn
		821
		822	Sets the C<log_cb> to simply use C<CORE::warn> to report any messages
		823	(usually this logs to STDERR).
		824
825	=item $ctx->log_to_file ($path)	825	=item $ctx->log_to_file ($path)
826		826
827	Sets the C<log_cb> to log to a file (by appending), unbuffered.	827	Sets the C<log_cb> to log to a file (by appending), unbuffered.
828		828
829	=item $ctx->log_to_path ($path)	829	=item $ctx->log_to_path ($path)
830		830
831	Same as C<< ->log_to_file >>, but opens the file for each message. This	831	Same as C<< ->log_to_file >>, but opens the file for each message. This
832	is much slower, but allows you to change/move/rename/delete the file at	832	is much slower, but allows you to change/move/rename/delete the file at
833	basically any time.	833	basically any time.
		834
		835	Needless(?) to say, if you do not want to be bitten by some evil person
		836	calling C<chdir>, the path should be absolute. Doesn't help with
		837	C<chroot>, but hey...
834		838
835	=item $ctx->log_to_syslog ([$log_flags])	839	=item $ctx->log_to_syslog ([$log_flags])
836		840
837	Logs all messages via L<Sys::Syslog>, mapping C<trace> to C<debug> and all	841	Logs all messages via L<Sys::Syslog>, mapping C<trace> to C<debug> and all
838	the others in the obvious way. If specified, then the C<$log_flags> are	842	the others in the obvious way. If specified, then the C<$log_flags> are
…		…
854	my ($ctx, $cb) = @_;	858	my ($ctx, $cb) = @_;
855		859
856	$ctx->[4] = $cb;	860	$ctx->[4] = $cb;
857	}	861	}
858		862
		863	sub log_to_warn {
		864	my ($ctx, $path) = @_;
		865
		866	$ctx->log_cb (sub {
		867	warn shift;
		868	0
		869	});
		870	}
		871
859	sub log_to_file {	872	sub log_to_file {
860	my ($ctx, $path) = @_;	873	my ($ctx, $path) = @_;
861		874
862	open my $fh, ">>", $path	875	open my $fh, ">>", $path
863	or die "$path: $!";	876	or die "$path: $!";
…		…
866	syswrite $fh, shift;	879	syswrite $fh, shift;
867	0	880	0
868	});	881	});
869	}	882	}
870		883
871	sub log_to_file {	884	sub log_to_path {
872	my ($ctx, $path) = @_;	885	my ($ctx, $path) = @_;
873		886
874	$ctx->log_cb (sub {	887	$ctx->log_cb (sub {
875	open my $fh, ">>", $path	888	open my $fh, ">>", $path
876	or die "$path: $!";	889	or die "$path: $!";
…		…
923	=cut	936	=cut
924		937
925	*log = \&AnyEvent::Log::_log;	938	*log = \&AnyEvent::Log::_log;
926	*logger = \&AnyEvent::Log::_logger;	939	*logger = \&AnyEvent::Log::_logger;
927		940
		941	=back
		942
		943	=cut
		944
		945	package AnyEvent::Log;
		946
		947	=head1 CONFIGURATION VIA $ENV{PERL_ANYEVENT_LOG}
		948
		949	Logging can also be configured by setting the environment variable
		950	C<PERL_ANYEVENT_LOG> (or C<AE_LOG>).
		951
		952	The value consists of one or more logging context specifications separated
		953	by C<:> or whitespace. Each logging specification in turn starts with a
		954	context name, followed by C<=>, followed by zero or more comma-separated
		955	configuration directives, here are some examples:
		956
		957	# set default logging level
		958	filter=warn
		959
		960	# log to file instead of to stderr
		961	log=file=/tmp/mylog
		962
		963	# log to file in addition to stderr
		964	log=+%file:%file=file=/tmp/mylog
		965
		966	# enable debug log messages, log warnings and above to syslog
		967	filter=debug:log=+%warnings:%warnings=warn,syslog=LOG_LOCAL0
		968
		969	# log trace messages (only) from AnyEvent::Debug to file
		970	AnyEvent::Debug=+%trace:%trace=only,trace,file=/tmp/tracelog
		971
		972	Since whitespace (which includes newlines) is allowed, it is fine to
		973	specify multiple lines in C<PERL_ANYEVENT_LOG>, e.g.:
		974
		975	PERL_ANYEVENT_LOG="
		976	filter=warn
		977	AnyEvent::Debug=+%trace
		978	%trace=only,trace,+log
		979	" myprog
		980
		981	A context name in the log specification can be any of the following:
		982
		983	=over 4
		984
		985	=item C<collect>, C<filter>, C<log>
		986
		987	Correspond to the three predefined C<$AnyEvent::Log::COLLECT>,
		988	C<AnyEvent::Log::FILTER> and C<$AnyEvent::Log::LOG> contexts.
		989
		990	=item C<%name>
		991
		992	Context names starting with a C<%> are anonymous contexts created when the
		993	name is first mentioned. The difference to package contexts is that by
		994	default they have no attached slaves.
		995
		996	=item a perl package name
		997
		998	Any other string references the logging context associated with the given
		999	Perl C<package>. In the unlikely case where you want to specify a package
		1000	context that matches on of the other context name forms, you can add a
		1001	C<::> to the package name to force interpretation as a package.
		1002
		1003	=back
		1004
		1005	The configuration specifications can be any number of the following:
		1006
		1007	=over 4
		1008
		1009	=item C<stderr>
		1010
		1011	Configures the context to use Perl's C<warn> function (which typically
		1012	logs to C<STDERR>). Works like C<log_to_warn>.
		1013
		1014	=item C<file=>I<path>
		1015
		1016	Configures the context to log to a file with the given path. Works like
		1017	C<log_to_file>.
		1018
		1019	=item C<path=>I<path>
		1020
		1021	Configures the context to log to a file with the given path. Works like
		1022	C<log_to_path>.
		1023
		1024	=item C<syslog> or C<syslog=>I<expr>
		1025
		1026	Configured the context to log to syslog. If I<expr> is given, then it is
		1027	evaluated in the L<Sys::Syslog> package, so you could use:
		1028
		1029	log=syslog=LOG_LOCAL0
		1030
		1031	=item C<nolog>
		1032
		1033	Configures the context to not log anything by itself, which is the
		1034	default. Same as C<< $ctx->log_cb (undef) >>.
		1035
		1036	=item C<0> or C<off>
		1037
		1038	Sets the logging level of the context ot C<0>, i.e. all messages will be
		1039	filtered out.
		1040
		1041	=item C<all>
		1042
		1043	Enables all logging levels, i.e. filtering will effectively be switched
		1044	off (the default).
		1045
		1046	=item C<only>
		1047
		1048	Disables all logging levels, and changes the interpretation of following
		1049	level specifications to enable the specified level only.
		1050
		1051	Example: only enable debug messages for a context.
		1052
		1053	context=only,debug
		1054
		1055	=item C<except>
		1056
		1057	Enables all logging levels, and changes the interpretation of following
		1058	level specifications to disable that level. Rarely used.
		1059
		1060	Example: enable all logging levels except fatal and trace (this is rather
		1061	nonsensical).
		1062
		1063	filter=exept,fatal,trace
		1064
		1065	=item C<level>
		1066
		1067	Enables all logging levels, and changes the interpretation of following
		1068	level specifications to be "that level or any higher priority
		1069	message". This is the default.
		1070
		1071	Example: log anything at or above warn level.
		1072
		1073	filter=warn
		1074
		1075	# or, more verbose
		1076	filter=only,level,warn
		1077
		1078	=item C<1>..C<9>, a logging level name (C<error>, C<debug> etc.)
		1079
		1080	A numeric loglevel or the name of a loglevel will be interpreted according
		1081	to the most recent C<only>, C<except> or C<level> directive. By default,
		1082	specifying a logging level enables that and any higher priority messages.
		1083
		1084	=item C<+>I<context>
		1085
		1086	Adds/attaches the named context as slave to the context.
		1087
		1088	=item C<+>
		1089
		1090	A line C<+> clears the slave list form the context. Anonymous (C<%name>)
		1091	contexts have no slaves by default, but package contexts have the parent
		1092	context as slave by default.
		1093
		1094	Example: log messages from My::Module to a file, do not send them to the
		1095	default log collector.
		1096
		1097	My::Module=+,file=/tmp/mymodulelog
		1098
		1099	=back
		1100
		1101	=cut
		1102
		1103	for (my $spec = $ENV{PERL_ANYEVENT_LOG}) {
		1104	my %anon;
		1105
		1106	my $pkg = sub {
		1107	$_[0] eq "log" ? $LOG
		1108	: $_[0] eq "filter" ? $FILTER
		1109	: $_[0] eq "collect" ? $COLLECT
		1110	: $_[0] =~ /^%(.+)$/ ? ($anon{$1} \|\|= ctx undef)
		1111	: $_[0] =~ /^(.*?)(?:::)?$/ ? ctx "$1" # egad :/
		1112	: die # never reached?
		1113	};
		1114
		1115	/\G[[:space:]]+/gc; # skip initial whitespace
		1116
		1117	while (/\G((?:[^:=[:space:]]+\|::\|\\.)+)=/gc) {
		1118	my $ctx = $pkg->($1);
		1119	my $level = "level";
		1120
		1121	while (/\G((?:[^,:[:space:]]+\|::\|\\.)+)/gc) {
		1122	for ("$1") {
		1123	if ($_ eq "stderr" ) { $ctx->log_to_warn;
		1124	} elsif (/^file=(.+)/ ) { $ctx->log_to_file ("$1");
		1125	} elsif (/^path=(.+)/ ) { $ctx->log_to_path ("$1");
		1126	} elsif (/syslog(?:=(.*))?/ ) { require Sys::Syslog; $ctx->log_to_syslog (eval "package Sys::Syslog; $1");
		1127	} elsif ($_ eq "nolog" ) { $ctx->log_cb (undef);
		1128	} elsif (/^\+(.+)$/ ) { $ctx->attach ($pkg->("$1"));
		1129	} elsif ($_ eq "+" ) { $ctx->slaves;
		1130	} elsif ($_ eq "off" or $_ eq "0") { $ctx->level (0);
		1131	} elsif ($_ eq "all" ) { $ctx->level ("all");
		1132	} elsif ($_ eq "level" ) { $ctx->level ("all"); $level = "level";
		1133	} elsif ($_ eq "only" ) { $ctx->level ("off"); $level = "enable";
		1134	} elsif ($_ eq "except" ) { $ctx->level ("all"); $level = "disable";
		1135	} elsif (/^\d$/ ) { $ctx->$level ($_);
		1136	} elsif (exists $STR2LEVEL{$_} ) { $ctx->$level ($_);
		1137	} else { die "PERL_ANYEVENT_LOG ($spec): parse error at '$_'\n";
		1138	}
		1139	}
		1140
		1141	/\G,/gc or last;
		1142	}
		1143
		1144	/\G[:[:space:]]+/gc or last;
		1145	}
		1146
		1147	/\G[[:space:]]+/gc; # skip trailing whitespace
		1148
		1149	if (/\G(.+)/g) {
		1150	die "PERL_ANYEVENT_LOG ($spec): parse error at '$1'\n";
		1151	}
		1152	}
		1153
928	1;	1154	1;
929		1155
930	=back
931
932	=head1 EXAMPLES	1156	=head1 EXAMPLES
933		1157
934	This section shows some common configurations.	1158	This section shows some common configurations, both as code, and as
		1159	C<PERL_ANYEVENT_LOG> string.
935		1160
936	=over 4	1161	=over 4
937		1162
938	=item Setting the global logging level.	1163	=item Setting the global logging level.
939		1164
940	Either put PERL_ANYEVENT_VERBOSE=<number> into your environment before	1165	Either put C<PERL_ANYEVENT_VERBOSE=><number> into your environment before
941	running your program, or modify the log level of the root context:	1166	running your program, use C<PERL_ANYEVENT_LOG> or modify the log level of
		1167	the root context at runtime:
942		1168
943	PERL_ANYEVENT_VERBOSE=5 ./myprog	1169	PERL_ANYEVENT_VERBOSE=5 ./myprog
944		1170
		1171	PERL_ANYEVENT_LOG=log=warn
		1172
945	$AnyEvent::Log::FILTER->level ("warn");	1173	$AnyEvent::Log::FILTER->level ("warn");
946		1174
947	=item Append all messages to a file instead of sending them to STDERR.	1175	=item Append all messages to a file instead of sending them to STDERR.
948		1176
949	This is affected by the global logging level.	1177	This is affected by the global logging level.
950		1178
951	$AnyEvent::Log::LOG->log_to_file ($path); (sub {	1179	$AnyEvent::Log::LOG->log_to_file ($path);
		1180
		1181	PERL_ANYEVENT_LOG=log=file=/some/path
952		1182
953	=item Write all messages with priority C<error> and higher to a file.	1183	=item Write all messages with priority C<error> and higher to a file.
954		1184
955	This writes them only when the global logging level allows it, because	1185	This writes them only when the global logging level allows it, because
956	it is attached to the default context which is invoked I<after> global	1186	it is attached to the default context which is invoked I<after> global
957	filtering.	1187	filtering.
958		1188
959	$AnyEvent::Log::FILTER->attach	1189	$AnyEvent::Log::FILTER->attach
960	new AnyEvent::Log::Ctx log_to_file => $path);	1190	new AnyEvent::Log::Ctx log_to_file => $path);
961		1191
		1192	PERL_ANYEVENT_LOG=filter=+%filelogger:%filelogger=file=/some/path
		1193
962	This writes them regardless of the global logging level, because it is	1194	This writes them regardless of the global logging level, because it is
963	attached to the toplevel context, which receives all messages I<before>	1195	attached to the toplevel context, which receives all messages I<before>
964	the global filtering.	1196	the global filtering.
965		1197
966	$AnyEvent::Log::COLLECT->attach (	1198	$AnyEvent::Log::COLLECT->attach (
967	new AnyEvent::Log::Ctx log_to_file => $path);	1199	new AnyEvent::Log::Ctx log_to_file => $path);
968		1200
		1201	PERL_ANYEVENT_LOG=%filelogger=file=/some/path:collect=+%filelogger
		1202
969	In both cases, messages are still written to STDERR.	1203	In both cases, messages are still written to STDERR.
970		1204
971	=item Write trace messages (only) from L<AnyEvent::Debug> to the default logging target(s).	1205	=item Write trace messages (only) from L<AnyEvent::Debug> to the default logging target(s).
972		1206
973	Attach the C<$AnyEvent::Log::LOG> context to the C<AnyEvent::Debug>	1207	Attach the C<$AnyEvent::Log::LOG> context to the C<AnyEvent::Debug>
974	context - this simply circumvents the global filtering for trace messages.	1208	context - this simply circumvents the global filtering for trace messages.
975		1209
976	my $debug = AnyEvent::Debug->AnyEvent::Log::ctx;	1210	my $debug = AnyEvent::Debug->AnyEvent::Log::ctx;
977	$debug->attach ($AnyEvent::Log::LOG);	1211	$debug->attach ($AnyEvent::Log::LOG);
		1212
		1213	PERL_ANYEVENT_LOG=AnyEvent::Debug=+log
978		1214
979	This of course works for any package, not just L<AnyEvent::Debug>, but	1215	This of course works for any package, not just L<AnyEvent::Debug>, but
980	assumes the log level for AnyEvent::Debug hasn't been changed from the	1216	assumes the log level for AnyEvent::Debug hasn't been changed from the
981	default.	1217	default.
982		1218
…		…
986		1222
987	Marc Lehmann <schmorp@schmorp.de>	1223	Marc Lehmann <schmorp@schmorp.de>
988	http://home.schmorp.de/	1224	http://home.schmorp.de/
989		1225
990	=cut	1226	=cut
		1227

Diff Legend

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

Comparing AnyEvent/lib/AnyEvent/Log.pm (file contents): Revision 1.24 by root, Sun Aug 21 03:24:59 2011 UTC vs. Revision 1.29 by root, Thu Aug 25 00:14:32 2011 UTC

Diff Legend

Comparing AnyEvent/lib/AnyEvent/Log.pm (file contents):
Revision 1.24 by root, Sun Aug 21 03:24:59 2011 UTC vs.
Revision 1.29 by root, Thu Aug 25 00:14:32 2011 UTC