1Catalyst::Stats(3) User Contributed Perl Documentation Catalyst::Stats(3)
2
6 Catalyst::Stats - Catalyst Timing Statistics Class
7
9 $stats = $c->stats;
10 $stats->enable(1);
11 $stats->profile($comment);
12 $stats->profile(begin => $block_name, comment =>$comment);
13 $stats->profile(end => $block_name);
14 $elapsed = $stats->elapsed;
15 $report = $stats->report;
16 See Catalyst.
18
20 This module provides the default, simple timing stats collection func‐
21 tionality for Catalyst. If you want something different set
22 "MyApp->stats_class" in your application module, e.g.:
23 __PACKAGE__->stats_class( "My::Stats" );
25 If you write your own, your stats object is expected to provide the
27 interface described here.
28 Catalyst uses this class to report timings of component actions. You
30 can add profiling points into your own code to get deeper insight. Typ‐
31 ical usage might be like this:
32 sub mysub {
34 my ($c, ...) = @_;
35 $c->stats->profile(begin => "mysub");
36 # code goes here
37 ...
38 $c->stats->profile("starting critical bit");
39 # code here too
40 ...
41 $c->stats->profile("completed first part of critical bit");
42 # more code
43 ...
44 $c->stats->profile("completed second part of critical bit");
45 # more code
46 ...
47 $c->stats->profile(end => "mysub");
48 }
49 Supposing mysub was called from the action "process" inside a Catalyst
51 Controller called "service", then the reported timings for the above
52 example might look something like this:
53 .----------------------------------------------------------------+-----------.
55 ⎪ Action ⎪ Time ⎪
56 +----------------------------------------------------------------+-----------+
57 ⎪ /service/process ⎪ 1.327702s ⎪
58 ⎪ mysub ⎪ 0.555555s ⎪
59 ⎪ - starting critical bit ⎪ 0.111111s ⎪
60 ⎪ - completed first part of critical bit ⎪ 0.333333s ⎪
61 ⎪ - completed second part of critical bit ⎪ 0.111000s ⎪
62 ⎪ /end ⎪ 0.000160s ⎪
63 '----------------------------------------------------------------+-----------'
64 which means mysub took 0.555555s overall, it took 0.111111s to reach
66 the critical bit, the first part of the critical bit took 0.333333s,
67 and the second part 0.111s.
68
70 new
71 Constructor.
73 $stats = Catalyst::Stats->new;
75 enable
77 $stats->enable(0);
79 $stats->enable(1);
80 Enable or disable stats collection. By default, stats are enabled
82 after object creation.
83 profile
85 $stats->profile($comment);
87 $stats->profile(begin => $block_name, comment =>$comment);
88 $stats->profile(end => $block_name);
89 Marks a profiling point. These can appear in pairs, to time the block
91 of code between the begin/end pairs, or by themselves, in which case
92 the time of execution to the previous profiling point will be reported.
93 The argument may be either a single comment string or a list of name-
95 value pairs. Thus the following are equivalent:
96 $stats->profile($comment);
98 $stats->profile(comment => $comment);
99 The following key names/values may be used:
101 * begin => ACTION
103 Marks the beginning of a block. The value is used in the descrip‐
104 tion in the timing report.
105 * end => ACTION
107 Marks the end of the block. The name given must match a previous
108 'begin'. Correct nesting is recommended, although this module is
109 tolerant of blocks that are not correctly nested, and the reported
110 timings should accurately reflect the time taken to execute the
111 block whether properly nested or not.
112 * comment => COMMENT
114 Comment string; use this to describe the profiling point. It is
115 combined with the block action (if any) in the timing report
116 description field.
117 * uid => UID
119 Assign a predefined unique ID. This is useful if, for whatever
120 reason, you wish to relate a profiling point to a different parent
121 than in the natural execution sequence.
122 * parent => UID
124 Explicitly relate the profiling point back to the parent with the
125 specified UID. The profiling point will be ignored if the UID has
126 not been previously defined.
127 Returns the UID of the current point in the profile tree. The UID is
129 automatically assigned if not explicitly given.
130 elapsed
132 $elapsed = $stats->elapsed
134 Get the total elapsed time (in seconds) since the object was created.
136 report
138 print $stats->report ."\n";
140 $report = $stats->report;
141 @report = $stats->report;
142 In scalar context, generates a textual report. In array context,
144 returns the array of results where each row comprises:
145 [ depth, description, time, rollup ]
147 The depth is the calling stack level of the profiling point.
149 The description is a combination of the block name and comment.
151 The time reported for each block is the total execution time for the
153 block, and the time associated with each intermediate profiling point
154 is the elapsed time from the previous profiling point.
155 The 'rollup' flag indicates whether the reported time is the rolled up
157 time for the block, or the elapsed time from the previous profiling
158 point.
159
161 Catalyst.
162
164 Jon Schutz
165
167 This program is free software, you can redistribute it and/or modify it
168 under the same terms as Perl itself.
169perl v5.8.8 2007-09-20 Catalyst::Stats(3)