Recording Values with Accumulators

In addition to counting Events, an application may define one or more other attributes, called Accumulators, to be associated with a given Event. Accumulators depend on the counter maintained by their parent Event object and use it for computing the average accumulation value of the Event over some period of time. Each Accumulator maintains four values: a sum, a sum of squares, a min, and a max. While the min and max values are reset at the beginning of each aggregation interval (otherwise, they would become meaningless over the lifetime of the application), the two sums are cumulative over the life of the Accumulator and are initialized to zero. For more information about the aggregation interval, see Configuring the Aggregation Interval.

As with other System Manager objects, to use an Accumulator it must first be looked up, which causes the object to be created if it has not been previously referenced:

Event recordableEvent = listener.lookupEvent(PCHeventClass.RPC, "eventName", false );
Accumulator accumEventValues = recordableEvent.lookupAccumulator("accumulatorName");

The accumulatorName is a Unicode String which provides the name for the Accumulator, which must be unique only within the scope of the associated Event, and may contain any printable characters excluding the newline character. As a result, several different Events could each have an Accumulator with the same name.

Once the Accumulator has been created, it may be used to record a series of values, each of which corresponds to the associated operation or Event, by calling the recordValue method:

accumEventValues.recordValue(value, [optional] includeEvent);

The value is a long, which will be added to the running total value of the Accumulator. It may cause the min or max values of the Accumulator to change, and its square will be added to the sum-of-squares value of the Accumulator.

The includeEvent parameter is an optional Boolean value (default is false), which indicates whether the value of the Event counter associated with this Accumulator should be incremented, when the Accumulator value is changed. This parameter enables the application to control when an Event counter is incremented, which is especially necessary if several accumulators are associated with the same Event in the application.

For a demonstration of how several accumulators can be associated with the same Event, see the examples in Implementation Considerations.

Using Events with Accumulators

Accumulators can be used whenever the application generates a sequence of values that are of interest to performance analysis. These values could be execution times (in the System Manager, this type of Accumulator is called a "duration" and is measured in nanoseconds), counts of the number of disk I/O operations, database queries, bytes transferred to/from disk, or similar values. In all of these cases, because the sequence of values itself is not maintained, but only the sum of the values, the count of the values must be available so that the average and standard deviation of the values over various periods of time can be computed by a Manager. Therefore, the association with an Event is critical because the Event counter is used to compute these values.