1Catalyst::Stats(3)    User Contributed Perl Documentation   Catalyst::Stats(3)
2
3
4

NAME

6       Catalyst::Stats - Catalyst Timing Statistics Class
7

SYNOPSIS

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
17       See Catalyst.
18

DESCRIPTION

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
24           __PACKAGE__->stats_class( "My::Stats" );
25
26       If you write your own, your stats object is expected to provide the
27       interface described here.
28
29       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
33         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
50       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
54         .----------------------------------------------------------------+-----------.
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
65       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

METHODS

70   new
71       Constructor.
72
73           $stats = Catalyst::Stats->new;
74
75   enable
76           $stats->enable(0);
77           $stats->enable(1);
78
79       Enable or disable stats collection.  By default, stats are enabled
80       after object creation.
81
82   profile
83           $stats->profile($comment);
84           $stats->profile(begin => $block_name, comment =>$comment);
85           $stats->profile(end => $block_name);
86
87       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
91       The argument may be either a single comment string or a list of name-
92       value pairs.  Thus the following are equivalent:
93
94           $stats->profile($comment);
95           $stats->profile(comment => $comment);
96
97       The following key names/values may be used:
98
99       •   begin => ACTION
100
101           Marks the beginning of a block.  The value is used in the
102           description in the timing report.
103
104       •   end => ACTION
105
106           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
112       •   comment => COMMENT
113
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
118       •   uid => UID
119
120           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
124       •   parent => UID
125
126           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
130       Returns the UID of the current point in the profile tree.  The UID is
131       automatically assigned if not explicitly given.
132
133   created
134           ($seconds, $microseconds) = $stats->created;
135
136       Returns the time the object was created, in "gettimeofday" format, with
137       Unix epoch seconds followed by microseconds.
138
139   elapsed
140           $elapsed = $stats->elapsed
141
142       Get the total elapsed time (in seconds) since the object was created.
143
144   report
145           print $stats->report ."\n";
146           $report = $stats->report;
147           @report = $stats->report;
148
149       In scalar context, generates a textual report.  In array context,
150       returns the array of results where each row comprises:
151
152           [ depth, description, time, rollup ]
153
154       The depth is the calling stack level of the profiling point.
155
156       The description is a combination of the block name and comment.
157
158       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
162       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

COMPATIBILITY METHODS

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
171   accept
172   addChild
173   setNodeValue
174   getNodeValue
175   traverse

SEE ALSO

177       Catalyst
178

AUTHORS

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.
185
186
187
188perl v5.38.0                      2023-07-24                Catalyst::Stats(3)
Impressum