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

Comparing AnyEvent/lib/AnyEvent/Log.pm (file contents):
Revision 1.22 by root, Sun Aug 21 02:19:30 2011 UTC vs.
Revision 1.63 by root, Wed Oct 29 20:41:17 2014 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	use AnyEvent;	9	use AnyEvent;
9		10
10	AE::log debug => "hit my knee";	11	AE::log fatal => "No config found, cannot continue!"; # never returns
11	AE::log warn => "it's a bit too hot";	12	AE::log alert => "The battery died!";
12	AE::log error => "the flag was false!";	13	AE::log crit => "The battery temperature is too hot!";
13	AE::log fatal => "the bit toggled! run!";	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";
		19	AE::log trace => "going to call function abc";
14		20
15	# "complex" use	21	Log level overview:
		22
		23	LVL NAME SYSLOG PERL NOTE
		24	1 fatal emerg exit system unusable, aborts program!
		25	2 alert failure in primary system
		26	3 critical crit failure in backup system
		27	4 error err die non-urgent program errors, a bug
		28	5 warn warning possible problem, not necessarily error
		29	6 note notice unusual conditions
		30	7 info normal messages, no action required
		31	8 debug debugging messages for development
		32	9 trace copious tracing output
		33
		34	"Complex" uses (for speed sensitive code, e.g. trace/debug messages):
		35
16	use AnyEvent::Log;	36	use AnyEvent::Log;
17		37
18	my $tracer = AnyEvent::Log::logger trace => \$my $trace;	38	my $tracer = AnyEvent::Log::logger trace => \$my $trace;
19		39
20	$tracer->("i am here") if $trace;	40	$tracer->("i am here") if $trace;
21	$tracer->(sub { "lots of data: " . Dumper $self }) if $trace;	41	$tracer->(sub { "lots of data: " . Dumper $self }) if $trace;
22		42
23	# configuration	43	Configuration (also look at the EXAMPLES section):
24		44
25	# set logging for the current package to errors and higher only	45	# set logging for the current package to errors and higher only
26	AnyEvent::Log::ctx->level ("error");	46	AnyEvent::Log::ctx->level ("error");
27		47
28	# set logging globally to anything below debug	48	# set logging level to suppress anything below "notice"
29	$AnyEvent::Log::FILTER->level ("notice");	49	$AnyEvent::Log::FILTER->level ("notice");
30		50
31	# see also EXAMPLES, below	51	# send all critical and higher priority messages to syslog,
		52	# regardless of (most) other settings
		53	$AnyEvent::Log::COLLECT->attach (new AnyEvent::Log::Ctx
		54	level => "critical",
		55	log_to_syslog => "user",
		56	);
32		57
33	=head1 DESCRIPTION	58	=head1 DESCRIPTION
34		59
35	This module implements a relatively simple "logging framework". It doesn't	60	This module implements a relatively simple "logging framework". It doesn't
36	attempt to be "the" logging solution or even "a" logging solution for	61	attempt to be "the" logging solution or even "a" logging solution for
37	AnyEvent - AnyEvent simply creates logging messages internally, and this	62	AnyEvent - AnyEvent simply creates logging messages internally, and this
38	module more or less exposes the mechanism, with some extra spiff to allow	63	module more or less exposes the mechanism, with some extra spiff to allow
39	using it from other modules as well.	64	using it from other modules as well.
40		65
41	Remember that the default verbosity level is C<0> (C<off>), so nothing	66	Remember that the default verbosity level is C<4> (C<error>), so only
42	will be logged, unless you set C<PERL_ANYEVENT_VERBOSE> to a higher number	67	errors and more important messages will be logged, unless you set
43	before starting your program, or change the logging level at runtime with	68	C<PERL_ANYEVENT_VERBOSE> to a higher number before starting your program
44	something like:	69	(C<AE_VERBOSE=5> is recommended during development), or change the logging
		70	level at runtime with something like:
45		71
46	use AnyEvent::Log;	72	use AnyEvent::Log;
47	AnyEvent::Log::FILTER->level ("info");	73	$AnyEvent::Log::FILTER->level ("info");
48		74
49	The design goal behind this module was to keep it simple (and small),	75	The design goal behind this module was to keep it simple (and small),
50	but make it powerful enough to be potentially useful for any module, and	76	but make it powerful enough to be potentially useful for any module,
51	extensive enough for the most common tasks, such as logging to multiple	77	and extensive enough for the most common tasks, such as logging to
52	targets, or being able to log into a database.	78	multiple targets, or being able to log into a database.
53		79
		80	The module is also usable before AnyEvent itself is initialised, in which
		81	case some of the functionality might be reduced.
		82
54	The amount of documentation might indicate otherwise, but the module is	83	The amount of documentation might indicate otherwise, but the runtime part
55	still just below 300 lines of code.	84	of the module is still just below 300 lines of code.
56		85
57	=head1 LOGGING LEVELS	86	=head1 LOGGING LEVELS
58		87
59	Logging levels in this module range from C<1> (highest priority) to C<9>	88	Logging levels in this module range from C<1> (highest priority) to C<9>
60	(lowest priority). Note that the lowest numerical value is the highest	89	(lowest priority). Note that the lowest numerical value is the highest
…		…
62	numerical value".	91	numerical value".
63		92
64	Instead of specifying levels by name you can also specify them by aliases:	93	Instead of specifying levels by name you can also specify them by aliases:
65		94
66	LVL NAME SYSLOG PERL NOTE	95	LVL NAME SYSLOG PERL NOTE
67	1 fatal emerg exit aborts program!	96	1 fatal emerg exit system unusable, aborts program!
68	2 alert	97	2 alert failure in primary system
69	3 critical crit	98	3 critical crit failure in backup system
70	4 error err die	99	4 error err die non-urgent program errors, a bug
71	5 warn warning	100	5 warn warning possible problem, not necessarily error
72	6 note notice	101	6 note notice unusual conditions
73	7 info	102	7 info normal messages, no action required
74	8 debug	103	8 debug debugging messages for development
75	9 trace	104	9 trace copious tracing output
76		105
77	As you can see, some logging levels have multiple aliases - the first one	106	As you can see, some logging levels have multiple aliases - the first one
78	is the "official" name, the second one the "syslog" name (if it differs)	107	is the "official" name, the second one the "syslog" name (if it differs)
79	and the third one the "perl" name, suggesting that you log C<die> messages	108	and the third one the "perl" name, suggesting (only!) that you log C<die>
80	at C<error> priority.	109	messages at C<error> priority. The NOTE column tries to provide some
		110	rationale on how to chose a logging level.
81		111
		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
		114	default. Levels 4..6 are meant for users and developers alike, while
		115	levels 7..9 are usually meant for developers.
		116
82	You can normally only log a single message at highest priority level	117	You can normally only log a message once at highest priority level (C<1>,
83	(C<1>, C<fatal>), because logging a fatal message will also quit the	118	C<fatal>), because logging a fatal message will also quit the program - so
84	program - so use it sparingly :)	119	use it sparingly :)
		120
		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.
85		124
86	Some methods also offer some extra levels, such as C<0>, C<off>, C<none>	125	Some methods also offer some extra levels, such as C<0>, C<off>, C<none>
87	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.
88		127
89	=head1 LOGGING FUNCTIONS	128	=head1 LOGGING FUNCTIONS
90		129
91	These functions allow you to log messages. They always use the caller's	130	The following functions allow you to log messages. They always use the
92	package as a "logging context". Also, the main logging function C<log> is	131	caller's package as a "logging context". Also, the main logging function,
93	callable as C<AnyEvent::log> or C<AE::log> when the C<AnyEvent> module is	132	C<log>, is aliased to C<AnyEvent::log> and C<AE::log> when the C<AnyEvent>
94	loaded.	133	module is loaded.
95		134
96	=over 4	135	=over 4
97		136
98	=cut	137	=cut
99		138
100	package AnyEvent::Log;	139	package AnyEvent::Log;
101		140
102	use Carp ();	141	use Carp ();
103	use POSIX ();	142	use POSIX ();
104		143
		144	# layout of a context
		145	# 0 1 2 3 4, 5
		146	# [$title, $level, %$slaves, &$logcb, &$fmtcb, $cap]
		147
105	use AnyEvent (); BEGIN { AnyEvent::common_sense }	148	use AnyEvent (); BEGIN { AnyEvent::common_sense }
106	use AnyEvent::Util ();	149	#use AnyEvent::Util (); need to load this in a delayed fashion, as it uses AE::log
107		150
108	our $VERSION = $AnyEvent::VERSION;	151	our $VERSION = $AnyEvent::VERSION;
109		152
110	our ($COLLECT, $FILTER, $LOG);	153	our ($COLLECT, $FILTER, $LOG);
111		154
112	our ($now_int, $now_str1, $now_str2);	155	our ($now_int, $now_str1, $now_str2);
113		156
114	# Format Time, not public - yet?	157	# Format Time, not public - yet?
115	sub ft($) {	158	sub format_time($) {
116	my $i = int $_[0];	159	my $i = int $_[0];
117	my $f = sprintf "%06d", 1e6 * ($_[0] - $i);	160	my $f = sprintf "%06d", 1e6 * ($_[0] - $i);
118		161
119	($now_int, $now_str1, $now_str2) = ($i, split /\x01/, POSIX::strftime "%Y-%m-%d %H:%M:%S.\x01 %z", localtime $i)	162	($now_int, $now_str1, $now_str2) = ($i, split /\x01/, POSIX::strftime "%Y-%m-%d %H:%M:%S.\x01 %z", localtime $i)
120	if $now_int != $i;	163	if $now_int != $i;
…		…
141	=item AnyEvent::Log::log $level, $msg[, @args]	184	=item AnyEvent::Log::log $level, $msg[, @args]
142		185
143	Requests logging of the given C<$msg> with the given log level, and	186	Requests logging of the given C<$msg> with the given log level, and
144	returns true if the message was logged I<somewhere>.	187	returns true if the message was logged I<somewhere>.
145		188
146	For C<fatal> log levels, the program will abort.	189	For loglevel C<fatal>, the program will abort.
147		190
148	If only a C<$msg> is given, it is logged as-is. With extra C<@args>, the	191	If only a C<$msg> is given, it is logged as-is. With extra C<@args>, the
149	C<$msg> is interpreted as an sprintf format string.	192	C<$msg> is interpreted as an sprintf format string.
150		193
151	The C<$msg> should not end with C<\n>, but may if that is convenient for	194	The C<$msg> should not end with C<\n>, but may if that is convenient for
…		…
153		196
154	Last not least, C<$msg> might be a code reference, in which case it is	197	Last not least, C<$msg> might be a code reference, in which case it is
155	supposed to return the message. It will be called only then the message	198	supposed to return the message. It will be called only then the message
156	actually gets logged, which is useful if it is costly to create the	199	actually gets logged, which is useful if it is costly to create the
157	message in the first place.	200	message in the first place.
		201
		202	This function takes care of saving and restoring C<$!> and C<$@>, so you
		203	don't have to.
158		204
159	Whether the given message will be logged depends on the maximum log level	205	Whether the given message will be logged depends on the maximum log level
160	and the caller's package. The return value can be used to ensure that	206	and the caller's package. The return value can be used to ensure that
161	messages or not "lost" - for example, when L<AnyEvent::Debug> detects a	207	messages or not "lost" - for example, when L<AnyEvent::Debug> detects a
162	runtime error it tries to log it at C<die> level, but if that message is	208	runtime error it tries to log it at C<die> level, but if that message is
…		…
196	info => 7,	242	info => 7,
197	debug => 8,	243	debug => 8,
198	trace => 9,	244	trace => 9,
199	);	245	);
200		246
201	sub now () { time }	247	our $TIME_EXACT;
		248
		249	sub exact_time($) {
		250	$TIME_EXACT = shift;
		251	*_ts = $AnyEvent::MODEL
		252	? $TIME_EXACT ? \&AE::now : \&AE::time
		253	: sub () { $TIME_EXACT ? do { require Time::HiRes; Time::HiRes::time () } : time };
		254	}
		255
		256	BEGIN {
		257	exact_time 0;
		258	}
202		259
203	AnyEvent::post_detect {	260	AnyEvent::post_detect {
204	*now = \&AE::now;	261	exact_time $TIME_EXACT;
205	};	262	};
206		263
207	our @LEVEL2STR = qw(0 fatal alert crit error warn note info debug trace);	264	our @LEVEL2STR = qw(0 fatal alert crit error warn note info debug trace);
208		265
209	# time, ctx, level, msg	266	# time, ctx, level, msg
210	sub _format($$$$) {	267	sub default_format($$$$) {
211	my $ts = ft $_[0];	268	my $ts = format_time $_[0];
212	my $ct = " ";	269	my $ct = " ";
213		270
214	my @res;	271	my @res;
215		272
216	for (split /\n/, sprintf "%-5s %s: %s", $LEVEL2STR[$_[2]], $_[1][0], $_[3]) {	273	for (split /\n/, sprintf "%-5s %s: %s", $LEVEL2STR[$_[2]], $_[1][0], $_[3]) {
…		…
219	}	276	}
220		277
221	join "", @res	278	join "", @res
222	}	279	}
223		280
		281	sub fatal_exit() {
		282	exit 1;
		283	}
		284
224	sub _log {	285	sub _log {
225	my ($ctx, $level, $format, @args) = @_;	286	my ($ctx, $level, $format, @args) = @_;
226		287
227	$level = $level > 0 && $level <= 9	288	$level = $level > 0 && $level <= 9
228	? $level+0	289	? $level+0
229	: $STR2LEVEL{$level} \|\| Carp::croak "$level: not a valid logging level, caught";	290	: $STR2LEVEL{$level} \|\| Carp::croak "$level: not a valid logging level, caught";
230		291
231	my $mask = 1 << $level;	292	my $mask = 1 << $level;
232		293
233	my ($success, %seen, @ctx, $now, $fmt);	294	my ($success, %seen, @ctx, $now, @fmt);
234		295
235	do	296	do
236	{	297	{
237	# skip if masked	298	# if !ref, then it's a level number
		299	if (!ref $ctx) {
		300	$level = $ctx;
238	if ($ctx->[1] & $mask && !$seen{$ctx+0}++) {	301	} elsif ($ctx->[1] & $mask and !$seen{$ctx+0}++) {
		302	# logging/recursing into this context
		303
		304	# level cap
		305	if ($ctx->[5] > $level) {
		306	push @ctx, $level; # restore level when going up in tree
		307	$level = $ctx->[5];
		308	}
		309
		310	# log if log cb
239	if ($ctx->[3]) {	311	if ($ctx->[3]) {
240	# logging target found	312	# logging target found
		313
		314	local ($!, $@);
241		315
242	# now get raw message, unless we have it already	316	# now get raw message, unless we have it already
243	unless ($now) {	317	unless ($now) {
244	$format = $format->() if ref $format;	318	$format = $format->() if ref $format;
245	$format = sprintf $format, @args if @args;	319	$format = sprintf $format, @args if @args;
246	$format =~ s/\n$//;	320	$format =~ s/\n$//;
247	$now = AE::now;	321	$now = _ts;
248	};	322	};
249		323
250	# format msg	324	# format msg
251	my $str = $ctx->[4]	325	my $str = $ctx->[4]
252	? $ctx->[4]($now, $_[0], $level, $format)	326	? $ctx->[4]($now, $_[0], $level, $format)
253	: ($fmt \|\|= _format $now, $_[0], $level, $format);	327	: ($fmt[$level] \|\|= default_format $now, $_[0], $level, $format);
254		328
255	$success = 1;	329	$success = 1;
256		330
257	$ctx->[3]($str)	331	$ctx->[3]($str)
258	or push @ctx, values %{ $ctx->[2] }; # not consumed - propagate	332	or push @ctx, values %{ $ctx->[2] }; # not consumed - propagate
…		…
261	}	335	}
262	}	336	}
263	}	337	}
264	while $ctx = pop @ctx;	338	while $ctx = pop @ctx;
265		339
266	exit 1 if $level <= 1;	340	fatal_exit if $level <= 1;
267		341
268	$success	342	$success
269	}	343	}
270		344
271	sub log($$;@) {	345	sub log($$;@) {
272	_log	346	_log
273	$CTX{ (caller)[0] } \|\|= _pkg_ctx +(caller)[0],	347	$CTX{ (caller)[0] } \|\|= _pkg_ctx +(caller)[0],
274	@_;	348	@_;
275	}	349	}
276		350
277	AnyEvent::log = AE::log = \&log;
278
279	=item $logger = AnyEvent::Log::logger $level[, \$enabled]	351	=item $logger = AnyEvent::Log::logger $level[, \$enabled]
280		352
281	Creates a code reference that, when called, acts as if the	353	Creates a code reference that, when called, acts as if the
282	C<AnyEvent::Log::log> function was called at this point with the given	354	C<AnyEvent::Log::log> function was called at this point with the given
283	level. C<$logger> is passed a C<$msg> and optional C<@args>, just as with	355	level. C<$logger> is passed a C<$msg> and optional C<@args>, just as with
…		…
347		419
348	$LOGGER{$logger+0} = $logger;	420	$LOGGER{$logger+0} = $logger;
349		421
350	_reassess $logger+0;	422	_reassess $logger+0;
351		423
		424	require AnyEvent::Util unless $AnyEvent::Util::VERSION;
352	my $guard = AnyEvent::Util::guard {	425	my $guard = AnyEvent::Util::guard (sub {
353	# "clean up"	426	# "clean up"
354	delete $LOGGER{$logger+0};	427	delete $LOGGER{$logger+0};
355	};	428	});
356		429
357	sub {	430	sub {
358	$guard if 0; # keep guard alive, but don't cause runtime overhead	431	$guard if 0; # keep guard alive, but don't cause runtime overhead
359		432
360	_log $ctx, $level, @_	433	_log $ctx, $level, @_
…		…
365	sub logger($;$) {	438	sub logger($;$) {
366	_logger	439	_logger
367	$CTX{ (caller)[0] } \|\|= _pkg_ctx +(caller)[0],	440	$CTX{ (caller)[0] } \|\|= _pkg_ctx +(caller)[0],
368	@_	441	@_
369	}	442	}
		443
		444	=item AnyEvent::Log::exact_time $on
		445
		446	By default, C<AnyEvent::Log> will use C<AE::now>, i.e. the cached
		447	eventloop time, for the log timestamps. After calling this function with a
		448	true value it will instead resort to C<AE::time>, i.e. fetch the current
		449	time on each log message. This only makes a difference for event loops
		450	that actually cache the time (such as L<EV> or L<AnyEvent::Loop>).
		451
		452	This setting can be changed at any time by calling this function.
		453
		454	Since C<AnyEvent::Log> has to work even before the L<AnyEvent> has been
		455	initialised, this switch will also decide whether to use C<CORE::time> or
		456	C<Time::HiRes::time> when logging a message before L<AnyEvent> becomes
		457	available.
		458
		459	=item AnyEvent::Log::format_time $timestamp
		460
		461	Formats a timestamp as returned by C<< AnyEvent->now >> or C<<
		462	AnyEvent->time >> or many other functions in the same way as
		463	C<AnyEvent::Log> does.
		464
		465	In your main program (as opposed to in your module) you can override
		466	the default timestamp display format by loading this module and then
		467	redefining this function.
		468
		469	Most commonly, this function can be used in formatting callbacks.
		470
		471	=item AnyEvent::Log::default_format $time, $ctx, $level, $msg
		472
		473	Format a log message using the given timestamp, logging context, log level
		474	and log message.
		475
		476	This is the formatting function used to format messages when no custom
		477	function is provided.
		478
		479	In your main program (as opposed to in your module) you can override the
		480	default message format by loading this module and then redefining this
		481	function.
		482
		483	=item AnyEvent::Log::fatal_exit
		484
		485	This is the function that is called after logging a C<fatal> log
		486	message. It must not return.
		487
		488	The default implementation simply calls C<exit 1>.
		489
		490	In your main program (as opposed to in your module) you can override
		491	the fatal exit function by loading this module and then redefining this
		492	function. Make sure you don't return.
370		493
371	=back	494	=back
372		495
373	=head1 LOGGING CONTEXTS	496	=head1 LOGGING CONTEXTS
374		497
…		…
494	This can be used to implement config-file (re-)loading: before loading a	617	This can be used to implement config-file (re-)loading: before loading a
495	configuration, reset all contexts.	618	configuration, reset all contexts.
496		619
497	=cut	620	=cut
498		621
		622	our $ORIG_VERBOSE = $AnyEvent::VERBOSE;
		623	$AnyEvent::VERBOSE = 9;
		624
499	sub reset {	625	sub reset {
500	# hard to kill complex data structures	626	# hard to kill complex data structures
501	# we "recreate" all package loggers and reset the hierarchy	627	# we "recreate" all package loggers and reset the hierarchy
502	while (my ($k, $v) = each %CTX) {	628	while (my ($k, $v) = each %CTX) {
503	@$v = ($k, (1 << 10) - 1 - 1, { });	629	@$v = ($k, (1 << 10) - 1 - 1, { });
…		…
506	}	632	}
507		633
508	@$_ = ($_->[0], (1 << 10) - 1 - 1)	634	@$_ = ($_->[0], (1 << 10) - 1 - 1)
509	for $LOG, $FILTER, $COLLECT;	635	for $LOG, $FILTER, $COLLECT;
510		636
511	$LOG->slaves;	637	#$LOG->slaves;
512	$LOG->title ('$AnyEvent::Log::LOG');	638	$LOG->title ('$AnyEvent::Log::LOG');
513	$LOG->log_cb (sub {	639	$LOG->log_to_warn;
514	warn shift;
515	0
516	});
517		640
518	$FILTER->slaves ($LOG);	641	$FILTER->slaves ($LOG);
519	$FILTER->title ('$AnyEvent::Log::FILTER');	642	$FILTER->title ('$AnyEvent::Log::FILTER');
520	$FILTER->level ($AnyEvent::VERBOSE);	643	$FILTER->level ($ORIG_VERBOSE);
521		644
522	$COLLECT->slaves ($FILTER);	645	$COLLECT->slaves ($FILTER);
523	$COLLECT->title ('$AnyEvent::Log::COLLECT');	646	$COLLECT->title ('$AnyEvent::Log::COLLECT');
524		647
525	_reassess;	648	_reassess;
526	}	649	}
		650
		651	# override AE::log/logger
		652	AnyEvent::log = AE::log = \&log;
		653	AnyEvent::logger = AE::logger = \&logger;
		654
		655	# convert AnyEvent loggers to AnyEvent::Log loggers
		656	$_->[0] = ctx $_->[0] # convert "pkg" to "ctx"
		657	for values %LOGGER;
527		658
528	# create the default logger contexts	659	# create the default logger contexts
529	$LOG = ctx undef;	660	$LOG = ctx undef;
530	$FILTER = ctx undef;	661	$FILTER = ctx undef;
531	$COLLECT = ctx undef;	662	$COLLECT = ctx undef;
…		…
540	package AnyEvent::Log::COLLECT;	671	package AnyEvent::Log::COLLECT;
541	package AE::Log::COLLECT;	672	package AE::Log::COLLECT;
542		673
543	package AnyEvent::Log::Ctx;	674	package AnyEvent::Log::Ctx;
544		675
545	# 0 1 2 3 4
546	# [$title, $level, %$slaves, &$logcb, &$fmtcb]
547
548	=item $ctx = new AnyEvent::Log::Ctx methodname => param...	676	=item $ctx = new AnyEvent::Log::Ctx methodname => param...
549		677
550	This is a convenience constructor that makes it simpler to construct	678	This is a convenience constructor that makes it simpler to construct
551	anonymous logging contexts.	679	anonymous logging contexts.
552		680
…		…
639		767
640	=item $ctx->disable ($level[, $level...])	768	=item $ctx->disable ($level[, $level...])
641		769
642	Disables logging for the given levels, leaving all others unchanged.	770	Disables logging for the given levels, leaving all others unchanged.
643		771
		772	=item $ctx->cap ($level)
		773
		774	Caps the maximum priority to the given level, for all messages logged
		775	to, or passing through, this context. That is, while this doesn't affect
		776	whether a message is logged or passed on, the maximum priority of messages
		777	will be limited to the specified level - messages with a higher priority
		778	will be set to the specified priority.
		779
		780	Another way to view this is that C<< ->level >> filters out messages with
		781	a too low priority, while C<< ->cap >> modifies messages with a too high
		782	priority.
		783
		784	This is useful when different log targets have different interpretations
		785	of priority. For example, for a specific command line program, a wrong
		786	command line switch might well result in a C<fatal> log message, while the
		787	same message, logged to syslog, is likely I<not> fatal to the system or
		788	syslog facility as a whole, but more likely a mere C<error>.
		789
		790	This can be modeled by having a stderr logger that logs messages "as-is"
		791	and a syslog logger that logs messages with a level cap of, say, C<error>,
		792	or, for truly system-critical components, actually C<critical>.
		793
644	=cut	794	=cut
645		795
646	sub _lvl_lst {	796	sub _lvl_lst {
647	map {	797	map {
648	$_ > 0 && $_ <= 9 ? $_+0	798	$_ > 0 && $_ <= 9 ? $_+0
649	: $_ eq "all" ? (1 .. 9)	799	: $_ eq "all" ? (1 .. 9)
650	: $STR2LEVEL{$_} \|\| Carp::croak "$_: not a valid logging level, caught"	800	: $STR2LEVEL{$_} \|\| Carp::croak "$_: not a valid logging level, caught"
651	} @_	801	} @_
652	}	802	}
653		803
		804	sub _lvl {
		805	$_[0] =~ /^(?:0\|off\|none)$/ ? 0 : (_lvl_lst $_[0])[-1]
		806	}
		807
654	our $NOP_CB = sub { 0 };	808	our $NOP_CB = sub { 0 };
655		809
656	sub levels {	810	sub levels {
657	my $ctx = shift;	811	my $ctx = shift;
658	$ctx->[1] = 0;	812	$ctx->[1] = 0;
…		…
661	AnyEvent::Log::_reassess;	815	AnyEvent::Log::_reassess;
662	}	816	}
663		817
664	sub level {	818	sub level {
665	my $ctx = shift;	819	my $ctx = shift;
666	my $lvl = $_[0] =~ /^(?:0\|off\|none)$/ ? 0 : (_lvl_lst $_[0])[-1];
667
668	$ctx->[1] = ((1 << $lvl) - 1) << 1;	820	$ctx->[1] = ((1 << &_lvl) - 1) << 1;
669	AnyEvent::Log::_reassess;	821	AnyEvent::Log::_reassess;
670	}	822	}
671		823
672	sub enable {	824	sub enable {
673	my $ctx = shift;	825	my $ctx = shift;
…		…
681	$ctx->[1] &= ~(1 << $_)	833	$ctx->[1] &= ~(1 << $_)
682	for &_lvl_lst;	834	for &_lvl_lst;
683	AnyEvent::Log::_reassess;	835	AnyEvent::Log::_reassess;
684	}	836	}
685		837
		838	sub cap {
		839	my $ctx = shift;
		840	$ctx->[5] = &_lvl;
		841	}
		842
686	=back	843	=back
687		844
688	=head3 SLAVE CONTEXTS	845	=head3 SLAVE CONTEXTS
689		846
690	The following methods attach and detach another logging context to a	847	The following methods attach and detach another logging context to a
…		…
742	the logging (which consists of formatting the message and printing it or	899	the logging (which consists of formatting the message and printing it or
743	whatever it wants to do with it).	900	whatever it wants to do with it).
744		901
745	=over 4	902	=over 4
746		903
747	=item $ctx->log_cb ($cb->($str)	904	=item $ctx->log_cb ($cb->($str))
748		905
749	Replaces the logging callback on the context (C<undef> disables the	906	Replaces the logging callback on the context (C<undef> disables the
750	logging callback).	907	logging callback).
751		908
752	The logging callback is responsible for handling formatted log messages	909	The logging callback is responsible for handling formatted log messages
…		…
777		934
778	Replaces the formatting callback on the context (C<undef> restores the	935	Replaces the formatting callback on the context (C<undef> restores the
779	default formatter).	936	default formatter).
780		937
781	The callback is passed the (possibly fractional) timestamp, the original	938	The callback is passed the (possibly fractional) timestamp, the original
782	logging context, the (numeric) logging level and the raw message string	939	logging context (object, not title), the (numeric) logging level and
783	and needs to return a formatted log message. In most cases this will be a	940	the raw message string and needs to return a formatted log message. In
784	string, but it could just as well be an array reference that just stores	941	most cases this will be a string, but it could just as well be an array
785	the values.	942	reference that just stores the values.
786		943
787	If, for some reaosn, you want to use C<caller> to find out more baout the	944	If, for some reason, you want to use C<caller> to find out more about the
788	logger then you should walk up the call stack until you are no longer	945	logger then you should walk up the call stack until you are no longer
789	inside the C<AnyEvent::Log> package.	946	inside the C<AnyEvent::Log> package.
790		947
		948	To implement your own logging callback, you might find the
		949	C<AnyEvent::Log::format_time> and C<AnyEvent::Log::default_format>
		950	functions useful.
		951
		952	Example: format the message just as AnyEvent::Log would, by letting
		953	AnyEvent::Log do the work. This is a good basis to design a formatting
		954	callback that only changes minor aspects of the formatting.
		955
		956	$ctx->fmt_cb (sub {
		957	my ($time, $ctx, $lvl, $msg) = @_;
		958
		959	AnyEvent::Log::default_format $time, $ctx, $lvl, $msg
		960	});
		961
791	Example: format just the raw message, with numeric log level in angle	962	Example: format just the raw message, with numeric log level in angle
792	brackets.	963	brackets.
793		964
794	$ctx->fmt_cb (sub {	965	$ctx->fmt_cb (sub {
795	my ($time, $ctx, $lvl, $msg) = @_;	966	my ($time, $ctx, $lvl, $msg) = @_;
796		967
797	"<$lvl>$msg\n"	968	"<$lvl>$msg\n"
798	});	969	});
799		970
800	Example: return an array reference with just the log values, and use	971	Example: return an array reference with just the log values, and use
801	C<PApp::SQL::sql_exec> to store the emssage in a database.	972	C<PApp::SQL::sql_exec> to store the message in a database.
802		973
803	$ctx->fmt_cb (sub { \@_ });	974	$ctx->fmt_cb (sub { \@_ });
804	$ctx->log_cb (sub {	975	$ctx->log_cb (sub {
805	my ($msg) = @_;	976	my ($msg) = @_;
806		977
…		…
811	"$msg->[3]";	982	"$msg->[3]";
812		983
813	0	984	0
814	});	985	});
815		986
		987	=item $ctx->log_to_warn
		988
		989	Sets the C<log_cb> to simply use C<CORE::warn> to report any messages
		990	(usually this logs to STDERR).
		991
816	=item $ctx->log_to_file ($path)	992	=item $ctx->log_to_file ($path)
817		993
818	Sets the C<log_cb> to log to a file (by appending), unbuffered.	994	Sets the C<log_cb> to log to a file (by appending), unbuffered. The
		995	function might return before the log file has been opened or created.
819		996
820	=item $ctx->log_to_path ($path)	997	=item $ctx->log_to_path ($path)
821		998
822	Same as C<< ->log_to_file >>, but opens the file for each message. This	999	Same as C<< ->log_to_file >>, but opens the file for each message. This
823	is much slower, but allows you to change/move/rename/delete the file at	1000	is much slower, but allows you to change/move/rename/delete the file at
824	basically any time.	1001	basically any time.
825		1002
		1003	Needless(?) to say, if you do not want to be bitten by some evil person
		1004	calling C<chdir>, the path should be absolute. Doesn't help with
		1005	C<chroot>, but hey...
		1006
826	=item $ctx->log_to_syslog ([$log_flags])	1007	=item $ctx->log_to_syslog ([$facility])
827		1008
828	Logs all messages via L<Sys::Syslog>, mapping C<trace> to C<debug> and all	1009	Logs all messages via L<Sys::Syslog>, mapping C<trace> to C<debug> and
829	the others in the obvious way. If specified, then the C<$log_flags> are	1010	all the others in the obvious way. If specified, then the C<$facility> is
830	simply or'ed onto the priority argument and can contain any C<LOG_xxx>	1011	used as the facility (C<user>, C<auth>, C<local0> and so on). The default
831	flags valid for Sys::Syslog::syslog, except for the priority levels.	1012	facility is C<user>.
832		1013
833	Note that this function also sets a C<fmt_cb> - the logging part requires	1014	Note that this function also sets a C<fmt_cb> - the logging part requires
834	an array reference with [$level, $str] as input.	1015	an array reference with [$level, $str] as input.
835		1016
836	=cut	1017	=cut
…		…
845	my ($ctx, $cb) = @_;	1026	my ($ctx, $cb) = @_;
846		1027
847	$ctx->[4] = $cb;	1028	$ctx->[4] = $cb;
848	}	1029	}
849		1030
		1031	sub log_to_warn {
		1032	my ($ctx, $path) = @_;
		1033
		1034	$ctx->log_cb (sub {
		1035	warn shift;
		1036	0
		1037	});
		1038	}
		1039
		1040	# this function is a good example of why threads are a must,
		1041	# simply for priority inversion.
		1042	sub _log_to_disk {
		1043	# eval'uating this at runtime saves 220kb rss - perl has become
		1044	# an insane memory waster.
		1045	eval q{ # poor man's autoloading {}
		1046	sub _log_to_disk {
		1047	my ($ctx, $path, $keepopen) = @_;
		1048
		1049	my $fh;
		1050	my @queue;
		1051	my $delay;
		1052	my $disable;
		1053
		1054	use AnyEvent::IO ();
		1055
		1056	my $kick = sub {
		1057	undef $delay;
		1058	return unless @queue;
		1059	$delay = 1;
		1060
		1061	# we pass $kick to $kick, so $kick itself doesn't keep a reference to $kick.
		1062	my $kick = shift;
		1063
		1064	# write one or more messages
		1065	my $write = sub {
		1066	# we write as many messages as have been queued
		1067	my $data = join "", @queue;
		1068	@queue = ();
		1069
		1070	AnyEvent::IO::aio_write $fh, $data, sub {
		1071	$disable = 1;
		1072	@_
		1073	? ($_[0] == length $data or AE::log 4 => "unable to write to logfile '$path': short write")
		1074	: AE::log 4 => "unable to write to logfile '$path': $!";
		1075	undef $disable;
		1076
		1077	if ($keepopen) {
		1078	$kick->($kick);
		1079	} else {
		1080	AnyEvent::IO::aio_close ($fh, sub {
		1081	undef $fh;
		1082	$kick->($kick);
		1083	});
		1084	}
		1085	};
		1086	};
		1087
		1088	if ($fh) {
		1089	$write->();
		1090	} else {
		1091	AnyEvent::IO::aio_open
		1092	$path,
		1093	AnyEvent::IO::O_CREAT \| AnyEvent::IO::O_WRONLY \| AnyEvent::IO::O_APPEND,
		1094	0666,
		1095	sub {
		1096	$fh = shift
		1097	or do {
		1098	$disable = 1;
		1099	AE::log 4 => "unable to open logfile '$path': $!";
		1100	undef $disable;
		1101	return;
		1102	};
		1103
		1104	$write->();
		1105	}
		1106	;
		1107	}
		1108	};
		1109
		1110	$ctx->log_cb (sub {
		1111	return if $disable;
		1112	push @queue, shift;
		1113	$kick->($kick) unless $delay;
		1114	0
		1115	});
		1116
		1117	$kick->($kick) if $keepopen; # initial open
		1118	};
		1119	};
		1120	die if $@;
		1121	&_log_to_disk
		1122	}
		1123
850	sub log_to_file {	1124	sub log_to_file {
851	my ($ctx, $path) = @_;	1125	my ($ctx, $path) = @_;
852		1126
853	open my $fh, ">>", $path	1127	_log_to_disk $ctx, $path, 1;
854	or die "$path: $!";
855
856	$ctx->log_cb (sub {
857	syswrite $fh, shift;
858	0
859	});
860	}	1128	}
861		1129
862	sub log_to_file {	1130	sub log_to_path {
863	my ($ctx, $path) = @_;	1131	my ($ctx, $path) = @_;
864		1132
865	$ctx->log_cb (sub {	1133	_log_to_disk $ctx, $path, 0;
866	open my $fh, ">>", $path
867	or die "$path: $!";
868
869	syswrite $fh, shift;
870	0
871	});
872	}	1134	}
873		1135
874	sub log_to_syslog {	1136	sub log_to_syslog {
875	my ($ctx, $flags) = @_;	1137	my ($ctx, $facility) = @_;
876		1138
877	require Sys::Syslog;	1139	require Sys::Syslog;
878		1140
879	$ctx->fmt_cb (sub {	1141	$ctx->fmt_cb (sub {
880	my $str = $_[3];	1142	my $str = $_[3];
881	$str =~ s/\n(?=.)/\n+ /g;	1143	$str =~ s/\n(?=.)/\n+ /g;
882		1144
883	[$_[2], "($_[1][0]) $str"]	1145	[$_[2], "($_[1][0]) $str"]
884	});	1146	});
885		1147
		1148	$facility \|\|= "user";
		1149
886	$ctx->log_cb (sub {	1150	$ctx->log_cb (sub {
887	my $lvl = $_[0][0] < 9 ? $_[0][0] : 8;	1151	my $lvl = $_[0][0] < 9 ? $_[0][0] : 8;
888		1152
889	Sys::Syslog::syslog ($flags \| ($lvl - 1), $_)	1153	Sys::Syslog::syslog ("$facility\|" . ($lvl - 1), $_)
890	for split /\n/, $_[0][1];	1154	for split /\n/, $_[0][1];
891		1155
892	0	1156	0
893	});	1157	});
894	}	1158	}
…		…
904		1168
905	=item $ctx->log ($level, $msg[, @params])	1169	=item $ctx->log ($level, $msg[, @params])
906		1170
907	Same as C<AnyEvent::Log::log>, but uses the given context as log context.	1171	Same as C<AnyEvent::Log::log>, but uses the given context as log context.
908		1172
		1173	Example: log a message in the context of another package.
		1174
		1175	(AnyEvent::Log::ctx "Other::Package")->log (warn => "heely bo");
		1176
909	=item $logger = $ctx->logger ($level[, \$enabled])	1177	=item $logger = $ctx->logger ($level[, \$enabled])
910		1178
911	Same as C<AnyEvent::Log::logger>, but uses the given context as log	1179	Same as C<AnyEvent::Log::logger>, but uses the given context as log
912	context.	1180	context.
913		1181
914	=cut	1182	=cut
915		1183
916	*log = \&AnyEvent::Log::_log;	1184	*log = \&AnyEvent::Log::_log;
917	*logger = \&AnyEvent::Log::_logger;	1185	*logger = \&AnyEvent::Log::_logger;
918		1186
919	1;
920
921	=back	1187	=back
922		1188
		1189	=cut
		1190
		1191	package AnyEvent::Log;
		1192
		1193	=head1 CONFIGURATION VIA $ENV{PERL_ANYEVENT_LOG}
		1194
		1195	Logging can also be configured by setting the environment variable
		1196	C<PERL_ANYEVENT_LOG> (or C<AE_LOG>).
		1197
		1198	The value consists of one or more logging context specifications separated
		1199	by C<:> or whitespace. Each logging specification in turn starts with a
		1200	context name, followed by C<=>, followed by zero or more comma-separated
		1201	configuration directives, here are some examples:
		1202
		1203	# set default logging level
		1204	filter=warn
		1205
		1206	# log to file instead of to stderr
		1207	log=file=/tmp/mylog
		1208
		1209	# log to file in addition to stderr
		1210	log=+%file:%file=file=/tmp/mylog
		1211
		1212	# enable debug log messages, log warnings and above to syslog
		1213	filter=debug:log=+%warnings:%warnings=warn,syslog=LOG_LOCAL0
		1214
		1215	# log trace messages (only) from AnyEvent::Debug to file
		1216	AnyEvent::Debug=+%trace:%trace=only,trace,file=/tmp/tracelog
		1217
		1218	A context name in the log specification can be any of the following:
		1219
		1220	=over 4
		1221
		1222	=item C<collect>, C<filter>, C<log>
		1223
		1224	Correspond to the three predefined C<$AnyEvent::Log::COLLECT>,
		1225	C<AnyEvent::Log::FILTER> and C<$AnyEvent::Log::LOG> contexts.
		1226
		1227	=item C<%name>
		1228
		1229	Context names starting with a C<%> are anonymous contexts created when the
		1230	name is first mentioned. The difference to package contexts is that by
		1231	default they have no attached slaves.
		1232
		1233	=item a perl package name
		1234
		1235	Any other string references the logging context associated with the given
		1236	Perl C<package>. In the unlikely case where you want to specify a package
		1237	context that matches on of the other context name forms, you can add a
		1238	C<::> to the package name to force interpretation as a package.
		1239
		1240	=back
		1241
		1242	The configuration specifications can be any number of the following:
		1243
		1244	=over 4
		1245
		1246	=item C<stderr>
		1247
		1248	Configures the context to use Perl's C<warn> function (which typically
		1249	logs to C<STDERR>). Works like C<log_to_warn>.
		1250
		1251	=item C<file=>I<path>
		1252
		1253	Configures the context to log to a file with the given path. Works like
		1254	C<log_to_file>.
		1255
		1256	=item C<path=>I<path>
		1257
		1258	Configures the context to log to a file with the given path. Works like
		1259	C<log_to_path>.
		1260
		1261	=item C<syslog> or C<syslog=>I<expr>
		1262
		1263	Configures the context to log to syslog. If I<expr> is given, then it is
		1264	evaluated in the L<Sys::Syslog> package, so you could use:
		1265
		1266	log=syslog=LOG_LOCAL0
		1267
		1268	=item C<nolog>
		1269
		1270	Configures the context to not log anything by itself, which is the
		1271	default. Same as C<< $ctx->log_cb (undef) >>.
		1272
		1273	=item C<cap=>I<level>
		1274
		1275	Caps logging messages entering this context at the given level, i.e.
		1276	reduces the priority of messages with higher priority than this level. The
		1277	default is C<0> (or C<off>), meaning the priority will not be touched.
		1278
		1279	=item C<0> or C<off>
		1280
		1281	Sets the logging level of the context to C<0>, i.e. all messages will be
		1282	filtered out.
		1283
		1284	=item C<all>
		1285
		1286	Enables all logging levels, i.e. filtering will effectively be switched
		1287	off (the default).
		1288
		1289	=item C<only>
		1290
		1291	Disables all logging levels, and changes the interpretation of following
		1292	level specifications to enable the specified level only.
		1293
		1294	Example: only enable debug messages for a context.
		1295
		1296	context=only,debug
		1297
		1298	=item C<except>
		1299
		1300	Enables all logging levels, and changes the interpretation of following
		1301	level specifications to disable that level. Rarely used.
		1302
		1303	Example: enable all logging levels except fatal and trace (this is rather
		1304	nonsensical).
		1305
		1306	filter=exept,fatal,trace
		1307
		1308	=item C<level>
		1309
		1310	Enables all logging levels, and changes the interpretation of following
		1311	level specifications to be "that level or any higher priority
		1312	message". This is the default.
		1313
		1314	Example: log anything at or above warn level.
		1315
		1316	filter=warn
		1317
		1318	# or, more verbose
		1319	filter=only,level,warn
		1320
		1321	=item C<1>..C<9> or a logging level name (C<error>, C<debug> etc.)
		1322
		1323	A numeric loglevel or the name of a loglevel will be interpreted according
		1324	to the most recent C<only>, C<except> or C<level> directive. By default,
		1325	specifying a logging level enables that and any higher priority messages.
		1326
		1327	=item C<+>I<context>
		1328
		1329	Attaches the named context as slave to the context.
		1330
		1331	=item C<+>
		1332
		1333	A lone C<+> detaches all contexts, i.e. clears the slave list from the
		1334	context. Anonymous (C<%name>) contexts have no attached slaves by default,
		1335	but package contexts have the parent context as slave by default.
		1336
		1337	Example: log messages from My::Module to a file, do not send them to the
		1338	default log collector.
		1339
		1340	My::Module=+,file=/tmp/mymodulelog
		1341
		1342	=back
		1343
		1344	Any character can be escaped by prefixing it with a C<\> (backslash), as
		1345	usual, so to log to a file containing a comma, colon, backslash and some
		1346	spaces in the filename, you would do this:
		1347
		1348	PERL_ANYEVENT_LOG='log=file=/some\ \:file\ with\,\ \\-escapes'
		1349
		1350	Since whitespace (which includes newlines) is allowed, it is fine to
		1351	specify multiple lines in C<PERL_ANYEVENT_LOG>, e.g.:
		1352
		1353	PERL_ANYEVENT_LOG="
		1354	filter=warn
		1355	AnyEvent::Debug=+%trace
		1356	%trace=only,trace,+log
		1357	" myprog
		1358
		1359	Also, in the unlikely case when you want to concatenate specifications,
		1360	use whitespace as separator, as C<::> will be interpreted as part of a
		1361	module name, an empty spec with two separators:
		1362
		1363	PERL_ANYEVENT_LOG="$PERL_ANYEVENT_LOG MyMod=debug"
		1364
		1365	=cut
		1366
		1367	for (my $spec = $ENV{PERL_ANYEVENT_LOG}) {
		1368	my %anon;
		1369
		1370	my $pkg = sub {
		1371	$_[0] eq "log" ? $LOG
		1372	: $_[0] eq "filter" ? $FILTER
		1373	: $_[0] eq "collect" ? $COLLECT
		1374	: $_[0] =~ /^%(.+)$/ ? ($anon{$1} \|\|= do { my $ctx = ctx undef; $ctx->[0] = $_[0]; $ctx })
		1375	: $_[0] =~ /^(.*?)(?:::)?$/ ? ctx "$1" # egad :/
		1376	: die # never reached?
		1377	};
		1378
		1379	/\G[[:space:]]+/gc; # skip initial whitespace
		1380
		1381	while (/\G((?:[^:=[:space:]]+\|::\|\\.)+)=/gc) {
		1382	my $ctx = $pkg->($1);
		1383	my $level = "level";
		1384
		1385	while (/\G((?:[^,:[:space:]]+\|::\|\\.)+)/gc) {
		1386	for ("$1") {
		1387	if ($_ eq "stderr" ) { $ctx->log_to_warn;
		1388	} elsif (/^file=(.+)/ ) { $ctx->log_to_file ("$1");
		1389	} elsif (/^path=(.+)/ ) { $ctx->log_to_path ("$1");
		1390	} elsif (/^syslog(?:=(.*))?/ ) { require Sys::Syslog; $ctx->log_to_syslog ("$1");
		1391	} elsif ($_ eq "nolog" ) { $ctx->log_cb (undef);
		1392	} elsif (/^cap=(.+)/ ) { $ctx->cap ("$1");
		1393	} elsif (/^\+(.+)$/ ) { $ctx->attach ($pkg->("$1"));
		1394	} elsif ($_ eq "+" ) { $ctx->slaves;
		1395	} elsif ($_ eq "off" or $_ eq "0") { $ctx->level (0);
		1396	} elsif ($_ eq "all" ) { $ctx->level ("all");
		1397	} elsif ($_ eq "level" ) { $ctx->level ("all"); $level = "level";
		1398	} elsif ($_ eq "only" ) { $ctx->level ("off"); $level = "enable";
		1399	} elsif ($_ eq "except" ) { $ctx->level ("all"); $level = "disable";
		1400	} elsif (/^\d$/ ) { $ctx->$level ($_);
		1401	} elsif (exists $STR2LEVEL{$_} ) { $ctx->$level ($_);
		1402	} else { die "PERL_ANYEVENT_LOG ($spec): parse error at '$_'\n";
		1403	}
		1404	}
		1405
		1406	/\G,/gc or last;
		1407	}
		1408
		1409	/\G[:[:space:]]+/gc or last;
		1410	}
		1411
		1412	/\G[[:space:]]+/gc; # skip trailing whitespace
		1413
		1414	if (/\G(.+)/g) {
		1415	die "PERL_ANYEVENT_LOG ($spec): parse error at '$1'\n";
		1416	}
		1417	}
		1418
923	=head1 EXAMPLES	1419	=head1 EXAMPLES
924		1420
925	This section shows some common configurations.	1421	This section shows some common configurations, both as code, and as
		1422	C<PERL_ANYEVENT_LOG> string.
926		1423
927	=over 4	1424	=over 4
928		1425
929	=item Setting the global logging level.	1426	=item Setting the global logging level.
930		1427
931	Either put PERL_ANYEVENT_VERBOSE=<number> into your environment before	1428	Either put C<PERL_ANYEVENT_VERBOSE=><number> into your environment before
932	running your program, or modify the log level of the root context:	1429	running your program, use C<PERL_ANYEVENT_LOG> or modify the log level of
		1430	the root context at runtime:
933		1431
934	PERL_ANYEVENT_VERBOSE=5 ./myprog	1432	PERL_ANYEVENT_VERBOSE=5 ./myprog
935		1433
		1434	PERL_ANYEVENT_LOG=log=warn
		1435
936	$AnyEvent::Log::FILTER->level ("warn");	1436	$AnyEvent::Log::FILTER->level ("warn");
937		1437
938	=item Append all messages to a file instead of sending them to STDERR.	1438	=item Append all messages to a file instead of sending them to STDERR.
939		1439
940	This is affected by the global logging level.	1440	This is affected by the global logging level.
941		1441
942	$AnyEvent::Log::LOG->log_to_file ($path); (sub {	1442	$AnyEvent::Log::LOG->log_to_file ($path);
		1443
		1444	PERL_ANYEVENT_LOG=log=file=/some/path
943		1445
944	=item Write all messages with priority C<error> and higher to a file.	1446	=item Write all messages with priority C<error> and higher to a file.
945		1447
946	This writes them only when the global logging level allows it, because	1448	This writes them only when the global logging level allows it, because
947	it is attached to the default context which is invoked I<after> global	1449	it is attached to the default context which is invoked I<after> global
948	filtering.	1450	filtering.
949		1451
950	$AnyEvent::Log::FILTER->attach	1452	$AnyEvent::Log::FILTER->attach (
951	new AnyEvent::Log::Ctx log_to_file => $path);	1453	new AnyEvent::Log::Ctx log_to_file => $path);
		1454
		1455	PERL_ANYEVENT_LOG=filter=+%filelogger:%filelogger=file=/some/path
952		1456
953	This writes them regardless of the global logging level, because it is	1457	This writes them regardless of the global logging level, because it is
954	attached to the toplevel context, which receives all messages I<before>	1458	attached to the toplevel context, which receives all messages I<before>
955	the global filtering.	1459	the global filtering.
956		1460
957	$AnyEvent::Log::COLLECT->attach (	1461	$AnyEvent::Log::COLLECT->attach (
958	new AnyEvent::Log::Ctx log_to_file => $path);	1462	new AnyEvent::Log::Ctx log_to_file => $path);
959		1463
		1464	PERL_ANYEVENT_LOG=%filelogger=file=/some/path:collect=+%filelogger
		1465
960	In both cases, messages are still written to STDERR.	1466	In both cases, messages are still written to STDERR.
		1467
		1468	=item Additionally log all messages with C<warn> and higher priority to
		1469	C<syslog>, but cap at C<error>.
		1470
		1471	This logs all messages to the default log target, but also logs messages
		1472	with priority C<warn> or higher (and not filtered otherwise) to syslog
		1473	facility C<user>. Messages with priority higher than C<error> will be
		1474	logged with level C<error>.
		1475
		1476	$AnyEvent::Log::LOG->attach (
		1477	new AnyEvent::Log::Ctx
		1478	level => "warn",
		1479	cap => "error",
		1480	syslog => "user",
		1481	);
		1482
		1483	PERL_ANYEVENT_LOG=log=+%syslog:%syslog=warn,cap=error,syslog
961		1484
962	=item Write trace messages (only) from L<AnyEvent::Debug> to the default logging target(s).	1485	=item Write trace messages (only) from L<AnyEvent::Debug> to the default logging target(s).
963		1486
964	Attach the C<$AnyEvent::Log::LOG> context to the C<AnyEvent::Debug>	1487	Attach the C<$AnyEvent::Log::LOG> context to the C<AnyEvent::Debug>
965	context - this simply circumvents the global filtering for trace messages.	1488	context - this simply circumvents the global filtering for trace messages.
966		1489
967	my $debug = AnyEvent::Debug->AnyEvent::Log::ctx;	1490	my $debug = AnyEvent::Debug->AnyEvent::Log::ctx;
968	$debug->attach ($AnyEvent::Log::LOG);	1491	$debug->attach ($AnyEvent::Log::LOG);
		1492
		1493	PERL_ANYEVENT_LOG=AnyEvent::Debug=+log
969		1494
970	This of course works for any package, not just L<AnyEvent::Debug>, but	1495	This of course works for any package, not just L<AnyEvent::Debug>, but
971	assumes the log level for AnyEvent::Debug hasn't been changed from the	1496	assumes the log level for AnyEvent::Debug hasn't been changed from the
972	default.	1497	default.
973		1498
974	=back	1499	=back
975		1500
		1501	=head1 ASYNCHRONOUS DISK I/O
		1502
		1503	This module uses L<AnyEvent::IO> to actually write log messages (in
		1504	C<log_to_file> and C<log_to_path>), so it doesn't block your program when
		1505	the disk is busy and a non-blocking L<AnyEvent::IO> backend is available.
		1506
976	=head1 AUTHOR	1507	=head1 AUTHOR
977		1508
978	Marc Lehmann <schmorp@schmorp.de>	1509	Marc Lehmann <schmorp@schmorp.de>
979	http://home.schmorp.de/	1510	http://anyevent.schmorp.de
980		1511
981	=cut	1512	=cut
		1513
		1514	1
		1515

Diff Legend

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

Comparing AnyEvent/lib/AnyEvent/Log.pm (file contents): Revision 1.22 by root, Sun Aug 21 02:19:30 2011 UTC vs. Revision 1.63 by root, Wed Oct 29 20:41:17 2014 UTC

Diff Legend

Comparing AnyEvent/lib/AnyEvent/Log.pm (file contents):
Revision 1.22 by root, Sun Aug 21 02:19:30 2011 UTC vs.
Revision 1.63 by root, Wed Oct 29 20:41:17 2014 UTC