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
21 functionality 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.
31 Typical 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.
72 $stats = Catalyst::Stats->new;
74 enable
76 $stats->enable(0);
77 $stats->enable(1);
78 Enable or disable stats collection. By default, stats are enabled
80 after object creation.
81 profile
83 $stats->profile($comment);
84 $stats->profile(begin => $block_name, comment =>$comment);
85 $stats->profile(end => $block_name);
86 Marks a profiling point. These can appear in pairs, to time the block
88 of code between the begin/end pairs, or by themselves, in which case
89 the time of execution to the previous profiling point will be reported.
90 The argument may be either a single comment string or a list of name-
92 value pairs. Thus the following are equivalent:
93 $stats->profile($comment);
95 $stats->profile(comment => $comment);
96 The following key names/values may be used:
98 • begin => ACTION
100 Marks the beginning of a block. The value is used in the
102 description in the timing report.
103 • end => ACTION
105 Marks the end of the block. The name given must match a previous
107 'begin'. Correct nesting is recommended, although this module is
108 tolerant of blocks that are not correctly nested, and the reported
109 timings should accurately reflect the time taken to execute the
110 block whether properly nested or not.
111 • comment => COMMENT
113 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
121 reason, you wish to relate a profiling point to a different parent
122 than in the natural execution sequence.
123 • parent => UID
125 Explicitly relate the profiling point back to the parent with the
127 specified UID. The profiling point will be ignored if the UID has
128 not been previously defined.
129 Returns the UID of the current point in the profile tree. The UID is
131 automatically assigned if not explicitly given.
132 created
134 ($seconds, $microseconds) = $stats->created;
135 Returns the time the object was created, in "gettimeofday" format, with
137 Unix epoch seconds followed by microseconds.
138 elapsed
140 $elapsed = $stats->elapsed
141 Get the total elapsed time (in seconds) since the object was created.
143 report
145 print $stats->report ."\n";
146 $report = $stats->report;
147 @report = $stats->report;
148 In scalar context, generates a textual report. In array context,
150 returns the array of results where each row comprises:
151 [ depth, description, time, rollup ]
153 The depth is the calling stack level of the profiling point.
155 The description is a combination of the block name and comment.
157 The time reported for each block is the total execution time for the
159 block, and the time associated with each intermediate profiling point
160 is the elapsed time from the previous profiling point.
161 The 'rollup' flag indicates whether the reported time is the rolled up
163 time for the block, or the elapsed time from the previous profiling
164 point.
165
167 Some components might expect the stats object to be a regular
168 Tree::Simple object. We've added some compatibility methods to handle
169 this scenario:
170 accept
172 addChild
173 setNodeValue
174 getNodeValue
175 traverse
177 Catalyst
178
180 Catalyst Contributors, see Catalyst.pm
181
183 This library is free software. You can redistribute it and/or modify it
184 under the same terms as Perl itself.
185perl v5.38.0 2023-07-24 Catalyst::Stats(3)