POE::Resource::Statistics -- experimental runtime statistics for POE
my %stats = $poe_kernel->stat_getdata; printf "Idle = %3.2f\n", 100*$stats{avg_idle_seconds}/$stats{interval};
POE::Resource::Statistics is a mix-in class for POE::Kernel. It provides features for gathering runtime statistics about POE::Kernel and the applications that use it.
Statistics gathering is enabled with the TRACE_STATISTICS constant. There is no runtime performance penalty when tracing is disabled.
Statistics are totaled every 30 seconds, and a rolling average is maintained for the last two minutes. The data may be retrieved at any time with the stat_getdata() method. Statistics will also be displayed on the console shortly before POE::Kernel's run() returns.
The time() function is used to gather statistics over time. If Time::HiRes is available, it will be used automatically. Otherwise time is measured in whole seconds, and the resulting rounding errors will make the statistics much less useful.
Runtime statistics gathering was added to POE 0.28. It is considered highly experimental. Please be advised that the statistics it gathers are quite likely wrong. They may in fact be useless. The reader is invited to investigate and improve the module's methodologies.
stat_getdata() returns a hashref with a small number of accumulated values. For each accumulator, there will be a corresponding field prefixed "avg_" which is the rolling average for that accumulator.
blocked contains the number of events (both user and kernel) which were delayed due to a user event running for too long. On conclusion of the program, POE will display the blocked count.
blocked
In theory, one can compare blocked with user_events to determine how much lag is produced by user code. blocked should be as low as possible to ensure minimum user-generated event lag.
user_events
In practice, blocked is often near or above user_events. Events that are even the slightest bit late count as being "blocked". See blocked_seconds for a potentially more useful metric.
blocked_seconds
blocked_seconds contains the total number of seconds that events waited in the queue beyond their nominal dispatch times. The average (avg_blocked_seconds) is generally more useful.
avg_blocked_seconds
idle_seconds is the amount of time that POE spent doing nothing at all. Typically this time is spent waiting for I/O or timers rather than dispatching events.
idle_seconds
interval is the average interval over which the statistics counters are recorded. This will typically be 30 seconds, but it can be more if long-running user events prevent statistics from being gathered on time. interval may also be less for programs that finish in under half a minute.
interval
avg_interval may often be lower, as the very last measurement taken before POE::Kernel's run() returns will almost always have an interval less than 30 seconds.
avg_interval
total_duration contains the total time over which the average was calculated. The "avg_" accumulators are averaged over a 2-minute interval. total_duration may vary from 120 seconds due to the same reasons as described in "interval".
total_duration
user_events contains the number of events that have been dispatched to user code. "User" events do not include POE's internal events, although it will include events dispatched on behalf of wheels.
Shortly before POE::Kernel's run() returns, a user_load value will be computed showing the average number of user events that have been dispatched per second. A very active web server should have a high user_load value. The higher the user load, the more important it is to have small blocked and blocked_seconds values.
user_load
user_seconds is the time that was spent handling user events, including those handled by wheels. user_seconds + idle_seconds should typically add up to total_duration. Any difference is unaccounted time in POE, and indicates a flaw in the statistics gathering methodology.
user_seconds
See "TRACE_STATISTICS" in POE::Kernel for instructions to enable statistics gathering.
Statistics may be highly inaccurate. This feature is highly experimental and may change significantly over time.
Contributed by Nick Williams <Nick.Williams@morganstanley.com>.
Please see POE for more information about authors and contributors.
To install POE, copy and paste the appropriate command in to your terminal.
cpanm
cpanm POE
CPAN shell
perl -MCPAN -e shell install POE
For more information on module installation, please visit the detailed CPAN module installation guide.