John Napiorkowski > Catalyst-Runtime-5.90020 > Catalyst::Stats

Download:
Catalyst-Runtime-5.90020.tar.gz

Dependencies

Annotate this POD

Website

CPAN RT

New  23
Open  15
Stalled  1
View/Report Bugs
Source   Latest Release: Catalyst-Runtime-5.90072

NAME ^

Catalyst::Stats - Catalyst Timing Statistics Class

SYNOPSIS ^

    $stats = $c->stats;
    $stats->enable(1);
    $stats->profile($comment);
    $stats->profile(begin => $block_name, comment =>$comment);
    $stats->profile(end => $block_name);
    $elapsed = $stats->elapsed;
    $report = $stats->report;

See Catalyst.

DESCRIPTION ^

This module provides the default, simple timing stats collection functionality for Catalyst. If you want something different set MyApp->stats_class in your application module, e.g.:

    __PACKAGE__->stats_class( "My::Stats" );

If you write your own, your stats object is expected to provide the interface described here.

Catalyst uses this class to report timings of component actions. You can add profiling points into your own code to get deeper insight. Typical usage might be like this:

  sub mysub {
    my ($c, ...) = @_;
    $c->stats->profile(begin => "mysub");
    # code goes here
    ...
    $c->stats->profile("starting critical bit");
    # code here too
    ...
    $c->stats->profile("completed first part of critical bit");
    # more code
    ...
    $c->stats->profile("completed second part of critical bit");
    # more code
    ...
    $c->stats->profile(end => "mysub");
  }

Supposing mysub was called from the action "process" inside a Catalyst Controller called "service", then the reported timings for the above example might look something like this:

  .----------------------------------------------------------------+-----------.
  | Action                                                         | Time      |
  +----------------------------------------------------------------+-----------+
  | /service/process                                               | 1.327702s |
  |  mysub                                                         | 0.555555s |
  |   - starting critical bit                                      | 0.111111s |
  |   - completed first part of critical bit                       | 0.333333s |
  |   - completed second part of critical bit                      | 0.111000s |
  | /end                                                           | 0.000160s |
  '----------------------------------------------------------------+-----------'

which means mysub took 0.555555s overall, it took 0.111111s to reach the critical bit, the first part of the critical bit took 0.333333s, and the second part 0.111s.

METHODS ^

new

Constructor.

    $stats = Catalyst::Stats->new;

enable

    $stats->enable(0);
    $stats->enable(1);

Enable or disable stats collection. By default, stats are enabled after object creation.

profile

    $stats->profile($comment);
    $stats->profile(begin => $block_name, comment =>$comment);
    $stats->profile(end => $block_name);

Marks a profiling point. These can appear in pairs, to time the block of code between the begin/end pairs, or by themselves, in which case the time of execution to the previous profiling point will be reported.

The argument may be either a single comment string or a list of name-value pairs. Thus the following are equivalent:

    $stats->profile($comment);
    $stats->profile(comment => $comment);

The following key names/values may be used:

Returns the UID of the current point in the profile tree. The UID is automatically assigned if not explicitly given.

created

    ($seconds, $microseconds) = $stats->created;

Returns the time the object was created, in gettimeofday format, with Unix epoch seconds followed by microseconds.

elapsed

    $elapsed = $stats->elapsed

Get the total elapsed time (in seconds) since the object was created.

report

    print $stats->report ."\n";
    $report = $stats->report;
    @report = $stats->report;

In scalar context, generates a textual report. In array context, returns the array of results where each row comprises:

    [ depth, description, time, rollup ]

The depth is the calling stack level of the profiling point.

The description is a combination of the block name and comment.

The time reported for each block is the total execution time for the block, and the time associated with each intermediate profiling point is the elapsed time from the previous profiling point.

The 'rollup' flag indicates whether the reported time is the rolled up time for the block, or the elapsed time from the previous profiling point.

COMPATIBILITY METHODS ^

Some components might expect the stats object to be a regular Tree::Simple object. We've added some compatibility methods to handle this scenario:

accept

addChild

setNodeValue

getNodeValue

traverse

SEE ALSO ^

Catalyst

AUTHORS ^

Catalyst Contributors, see Catalyst.pm

COPYRIGHT ^

This library is free software. You can redistribute it and/or modify it under the same terms as Perl itself.

syntax highlighting: