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 <keroyon@cpan.org>

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.

