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/Tokyo YAML 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 add more tests fix this pod AUTHOR keroyon SEE ALSO Log::Dispatch::Config Log::Dispatch Log::WarnDie LICENSE This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.