NAME
Log::Dispatch::Config::Watcher - Subclass of Log::Dispatch::Config that observes the start and the end of functions
SYNOPSIS
#---------- code ----------
use Log::Dispatch::Config::Watcher;
use Log::Dispatch::Configurator::YAML;
my $config = Log::Dispatch::Configurator::YAML->new('/path/to/log.yaml');
Log::Dispatch::Config::Watcher->configure($config);
my $log = Log::Dispatch::Config::Watcher->instance;
$log->info('log message');
test1();
test2();
test3();
sub test1 { # observed + warn
$log->warn('sample warning.');
sleep 4;
}
sub test2 { # not observed + exepected die(eval) + warn
eval { die 'die with expected exception'; };
warn $@ if $@;
}
sub test3 { # observed + unexpected die(not eval)
sleep 5;
die 'die with unexpected exception.';
}
#---------- YAML file ---------- YAML format strongly recommended
dispatchers:
- screen
screen:
class: Log::Dispatch::Screen
min_level: debug
format: '[%p] %F:%L %m [%D{%F %T.%6N%z}]' # see DateTime::Format::Strptime
newline: 1
stderr: 1
watch:
watch_die: 1 # watching perl's die method.
watch_only_unexpected_die: 1
watch_warn: 1 # watching perl's warn method.
die_level: critical
warn_level: warning
formats:
start: '[%p] START:%j [%D{%F %T.%6N%z}]'
end: '[%p] END:%j(%t) [%D{%F %T.%6N%z}]'
end_with_die: '[%p] ABNORMALLY_ENDED:%j(%e) [%D{%F %T.%6N%z}]'
die: '[%p] UNEXPECTED_DIE (%e) [%D{%F %T.%6N%z}]'
warn: '[%p] PERL_WARNING (%e) [%D{%F %T.%6N%z}]'
timeover: '[%p] TIMEOVER:%j(%t)'
functions:
main::test1: # function name. Don't forget adding the package name.
description: sleep 4 seconds process
warn_duration: 5.0 # write seconds.
notice_duration: 3.5
main::test3:
description: sleep 5 seconds process
warn_duration: 4.0
notice_duration: 2.5
#---------- results ----------
[info] ./log.pl:13 log message [2010-07-30 15:34:16.316215+0900]
[info] START:"sleep 4 seconds process" [2010-07-30 15:34:16.319123+0900]
[warn] ./log.pl:19 sample warning. [2010-07-30 15:34:16.320854+0900]
[notice] TIMEOVER:"sleep 4 seconds process"(=>00:00:04.005179167)
[info] END:"sleep 4 seconds process"(=>00:00:04.005179167) [2010-07-30 15:34:20.324692+0900]
[warning] PERL_WARNING (die with expected exception at ./log.pl line 25.)
[info] START:"sleep 5 seconds process" [2010-07-30 15:34:25.328754+0900]
[warning] TIMEOVER:"sleep 5 seconds process"(=>00:00:05.00351812)
[critical] ABNORMALLY_ENDED:"sleep 5 seconds process"(die with unexpected exception. at ./log.pl line 30.) [2010-07-30 15:34:25.330754+0900]POD BUGS
This POD does'nt make sense because my English Sux.
The best way to understand the usage of this module is reading the "SYNOPSIS" section.
Reading the "DESCRIPTION" section makes you confusing, I guess.
DESCRIPTION
This is a subclass of Log::Dispatch::Config that watches the start and the end of functions, warn and die.
Watch object
- 1. The start and end of the function
-
This class watches the start and the end of the function whose name is defined in a config file, and outputs the log whose format is defined in a config file.
Moreover, the log level can be switched based on the elapsed time.
- 2. Warn and die
-
This class watches the perl's warn and die.
When the warn or die is invoked, it is converted into the Log::Dispatch::log method.
SEE ALSO Log::WarnDie
Enhancing of format character
- %j
-
Explanation of the function (watch.formats.functions.[function name].description)
- %e
-
Error message of warn and die ($@)
- %t
-
Execution time of function to be observed
- %D{...}
-
Output format of time which is passed to DateTime::Format::Strptime.
format list
- watch.formats.start
-
Log format that is used when the function is started.
- watch.formats.end
-
Log format that is used when the function is ended.
- watch.formats.end_with_die
-
Log format that is used when the function is died.
- watch.formats.timeover
-
Log format that is used when the execution time of the function ran over "warn_duration" or "notice_duration" time.
- watch.formats.die
-
Log format that is used when the program is died.
- watch.formats.warn
-
Log format that is used when the program calls a warn method.
CONFIGURATION
Here is an example of the config file:
dispatchers:
- screen
screen:
class: Log::Dispatch::Screen
min_level: debug
format: '[%p] %F:%L %m [%D{%F %T.%6N%z}]'
newline: 1
stderr: 1
watch:
watch_die: 1
watch_only_unexpected_die: 1
watch_warn: 1
die_level: critical
warn_level: warning
formats:
start: '[%p] START:%j [%D{%F %T.%6N%z}]'
end: '[%p] END:%j(%t) [%D{%F %T.%6N%z}]'
end_with_die: '[%p] ABNORMALLY_ENDED:%j(%e) [%D{%F %T.%6N%z}]'
die: '[%p] UNEXPECTED_DIE (%e) [%D{%F %T.%6N%z}]'
warn: '[%p] PERL_WARNING (%e)'
timeover: '[%p] TIMEOVER:%j(%t)'
functions:
main::test1:
description: sleep some seconds process
warn_duration: 5.0
notice_duration: 3.5
main::test2:
description: sleep some seconds process
warn_duration: 4.0
notice_duration: 2.5
time_zone: Asia/TokyoYAML format is strongly recommended.
- watch.watch_die
-
Disabling or enabling the watching of the perl's die. default is 0.
- watch.watch_only_unexpected_die
-
Disabling or enabling the watching of the perl's die. default is 0.
- watch.watch_warn
-
Disabling or enabling the watching of the perl's warn. default is 0.
- watch.die_level
-
default is critical.
- watch.warn_level
-
default is warning.
- watch.formats
-
see DESCRIPTION section.
- watch.functions
DEPENDENCIES
- Log::Dispatch::Config
- Hook::LexWrap
- DateTime
- DateTime::HiRes
- DateTime::Format::Strptime
- DateTime::Duration
- DateTime::Format::Duration
TODO
AUTHOR
keroyon <keroyon@cpan.org>
SEE ALSO
LICENSE
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.