NAME

Aspect::Library::ZoneTimer - Generate named time cost breakdowns

SYNOPSIS

  use Aspect;
  use Aspect::Library::ZoneTimer;
  
  use Aspect;
  
  aspect ZoneTimer => (
      zones => {
          main      => call 'MyProgram::main' & highest,
          search    => call 'MyProgram::search',
          widgets   => call qr/^MyProgram::widget_.*/,
          templates => call 'MyProgram::render',
          dbi       => call qr/^DB[DI]::.*?\b(?:prepare|execute|fetch.*)$/,
          system    => (
              call qr/^IPC::System::Simple::(?:run|runx|capture)/
              |
              call 'IPC::Run3::run3'
              |
              call qr/^Capture::Tiny::(?:capture|tee).*/
          )
      },
      handler => sub {
          my $top       = shift; # "main"
          my $start     = shift; # [ 1279763446, 796875 ]
          my $stop      = shift; # [ 1279763473, 163153 ]
          my $exclusive = shift; # { main => 23123412, dbi => 3231231 }
   
          print "Profiling from zone $top\n";
          print "Started recording at " . scalar(localtime $start->[0]) . "\n";
          print "Stopped recording at " . scalar(localtime $stop->[0])  . "\n";
          foreach my $zone ( sort keys %$exclusive ) {
              print "Spent $exclusive->{$zone} microseconds in zone $zone\n";
          }
      },
  );

DESCRIPTION

While a full profiler like Devel::NYTProf is great for development and analysis, it is generally far too slow and generates too much data to run it on a production machine.

Aspect::Library::ZoneTimer is designed to provide some of the same benefits of a regular profiler, but in a way that can be deployed onto one or many production servers.

The ZoneTimer aspect lets you break up your program into a series of named "zones" based on the areas in which you expect your program will expend the most wallclock time.

In the example above, we expect that most of the program time will be spent either parsing Perl files using PPI (which we know to be slow) or waiting for a response from our database of some kind. We also define a top zone that we expect to enter as soon as the program starts to do useful work.

Each zone is defined by a Aspect::Pointcut that identifies the key functions that serve as entry points for that area of the program.

As your program executes, the ZoneTimer will watch at these zone entry points, and track the progress of your program as it moves between the different zones.

The wallclock time for the execution is tallied up both inclusive and exclusive for each zone, and when the top-most zone exits the results are handed off to a handler callback so you can write the times to disk, save them to a database, or send them to a local or remote syslog.

For maximum accuracy, the start/stop times and the exclusive totals are provided in two different formats.

Start and stop times are provided as a reference to a two-element ARRAY exactly as returned by Time::HiRes.

The profile totals are provided as a reference to a HASH where the keys are the zone names, and the values are the exclusive wallclock time for the zone in microseconds.

All timer math is done internally with these integer microseconds to prevent floating point bugs creeping into the results, and ZoneTimer will avoid manipulating these

SUPPORT

Bugs should be reported via the CPAN bug tracker at

http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Aspect-Library-Timer

For other issues, contact the author.

AUTHOR

Adam Kennedy <adamk@cpan.org>

SEE ALSO

Aspect, Aspect::Library::Timer

COPYRIGHT

Copyright 2010 - 2012 Adam Kennedy.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.