Recording Values with Accumulators

In addition to counting Events, an application can define one or more other attributes that are called Accumulators to be associated with a specified Event. Accumulators depend on the counter that is maintained by their parent Event object and use it for computing the average accumulation value of the Event over 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 API objects to use an Accumulator, it must first be looked up, which causes the object to be created if it was not previously referenced:

Event *recordableEvent = listener->lookupEvent(eventClass, "eventName");
Accumulator *accumEventValues = recordableEvent->lookupAccumulator("accumulatorName");

The accumulatorName is a string that provides the name for the Accumulator, which must be unique only within the scope of the associated Event. As a result, several different Events can have an Accumulator with the same name. The lookupAccumulator constructor is overloaded to allow the string to be passed as Unicode const wchar_t * that contains any printable UTF-8 characters, excluding the newline character. It creates an Accumulator object only when that object does not currently exist. If the object exists, the existing object is returned.

The created Accumulator can be used to record a series of values, which correspond to the associated operation or Event, by calling the recordValue member function:

accumEventValues->recordValue(value, [optional] includeEvent);

The value is a 64-bit unsigned int, which is added to the running total value of the Accumulator. It can cause the min or max values of the Accumulator to change, and its square is 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 can 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.

Associating Events with Accumulators

Accumulators can be used whenever the application generates a sequence of values that are of interest to performance analysis. These values can be execution times, counts of the number of disk I/O operations, database queries, bytes transferred to/from disk, or similar values. When the values are execution times inIBM® System Dashboard for Enterprise Content Management, this type of Accumulator is called a "duration" and is measured in nanoseconds. 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.