POE::Resource::Statistics -- Runtime statistics for POE programs

  my %stats = $poe_kernel->stat_getdata;
  printf "Idle = %3.2f\n", 100*$stats{avg_idle_seconds}/$stats{interval};

This module tracks runtime statistics for a POE program and provides accessors to them. To enable this monitoring, the TRACE_STATISTICS flag must be true. Otherwise no statistics will be gathered.

The statistics counters are totaled every 30 seconds and a rolling average is maintained for the last two minutes worth of data. At any time the data can be retrieved using the stat_getdata() method of the POE::Kernel. On conclusion of the program, the statistics will be printed out by the POE::Kernel.

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 useless.

Runtime statistics gathering was added to POE 0.28. It is considered highly experimental. Please be advised that the figures are quite likely wrong. They may in fact be useless. The reader is invited to investigate and improve the module's methods.

The following fields are members of the hash returned by stat_getdata().

For each of the counters, there will a corresponding entry prefixed 'avg_' which is the rolling average of that counter.

blocked

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. By comparing this value with user_events. This value should be as low as possible to ensure minimal latency. In practice, this number is very close to (or even above) user_events. Events that are even the slightest bit late count as blocked. See blocked_seconds. TODO - Perhaps this should only count events that were dispatched more than 1/100 second or so late? Even then, the hundredths add up in long running programs.

blocked_seconds

The total number of seconds that handlers waited for other events or POE before being dispatched. This value is not as useful as its average version, avg_blocked_seconds, which tells you the average latency between an event's due time and its dispatch time.

idle_seconds

The number of seconds which were spent doing nothing at all (typically waiting for a select/poll event or a timeout to trigger).

interval

The average interval over which the counters are recorded. This will typically be 30 seconds, however it can be more if there are long-running user events which prevent the statistics gathering from running on time, and it may be less if the program finishes in under 30 seconds. Often the very last measurement taken before the program exits will use a duration less than 30 seconds and this will cause the average to be lower.

total_duration

The counters are averaged over a 2 minute duration, but for the same reasons as described in the interval section, this time may vary. This value contains the total time over which the average was calculated.

user_events

The number of events which are performed for the user code. I.e. this does not include POE's own internal events such as polling for child processes. At program termination, a user_load value is computed showing the average number of user events which are running per second. A very active web server would have a high load value. The higher the user load, the more important it is that you have small blocked and blocked_seconds values.

user_seconds

The time which was spent running user events. The user_seconds + idle_seconds will typically add up to total_duration. Any difference comes down to time spent in the POE kernel (which should be minimal) and rounding errors.

See POE::Kernel.

Probably.

Contributed by Nick Williams <Nick.Williams@morganstanley.com>.

Please see POE for more information about authors and contributors.