Recording Events

An Event is used as a counter for some activity that occurs within the application. Events are recorded through the use of Event objects which may be created at the top level of the Listener:

Listener listener("appName", "appVersion");
Event toplevelEvent = listener.lookupEvent([PCHeventClass.RPC || PCHeventClass.USER], "eventName",
[optional]    includeParent);

or as a subordinate to a Container:

Container eventContainer = listener.lookupContainer("containerName");
Event event = eventContainer.lookupEvent([PCHeventClass.RPC || PCHeventClass.USER], "eventName",
[optional] includeParent);

or as a subordinate to another Event as a sub-Event:

Event subEvent = event.lookupEvent("eventName", [optional] includeParent);

Each Event object has a 64-bit counter that increases cumulatively over the lifetime of the object (which is also the lifetime of the Listener). The initial value of the counter is set to zero and may be incremented using the recordEvent method.

The PCHeventClass parameter of the constructor is an instance of the PCHeventClass class that specifies the class of the event. This is a type safe enumeration in Java™ which is limited to the pre-created definitions PCHeventClass.RPC (to record top level client requests) and PCHeventClass.USER (to record any other type of Event or operation occurring in the application). In addition to these two class types, the Listener also automatically generates data in three other classes: DISK, NETWORK, and CPU. (This parameter is not specified when creating a subordinate Event of another Event object because the event class of the subordinate Event must be the same as that employed by the parent Event object.)

The eventName parameter is a Unicode String which provides the name for the Event and may contain any printable characters excluding the newline character. The includeParent parameter is an optional Boolean value (default is false) that indicates whether the recordEvent method of the parent Event object should also be called, when the counter for the sub-Event is incremented.

Creating Subordinate Objects

Once created, the application may create subordinate objects for the Event, including Meters, Accumulators, or other Events, called sub-Events.

Accumulators depend on the counter maintained by their parent Event object and use it for computing the average accumulation value over some period of time. For more information about working with Accumulators, see Recording Values with Accumulators.

Meters are similar to Accumulators, except they maintain absolute values and may be used for reporting the aggregation intervals of these values over time. For more information about working with Meters, see Reporting Performance Data with Meters.

Creating sub-Events

A sub-Event automatically inherits the event class of the parent Event object and may be used to represent a significant activity that sometimes or always occurs while performing the higher-level Event, or it may also represent a refined Event counter.

For example, suppose the application is configured to respond to an RPC Event named RPCEventOne and that when servicing RPCEventOne, a significant subroutine SubroutineOne is sometimes called. The application may choose to record the number of times SubroutineOne is called, as well as the total processing time for the subroutine. In this case, the application would implement the following Events:

Event RPCEventOne = listener.lookupEvent(PCHeventClass.RPC, "RPC Event One", true);
Event RPCSubEventOne = RPCEventOne.lookupEvent("RPC SubEvent One", true);

Tip: Separate Duration objects may also be declared for duration Accumulators associated with each of these Event objects. For more information, see Measuring Elapsed Time with Durations

Auto-incrementing Parent Event Counters

sub-Events may also be created such that when their recordEvent method is called to increment the Event counter, then the counter for the parent Event is also automatically incremented by the same amount. This type of sub-Event is created by specifying true for the includeParent parameter of the constructor.

As an example, suppose the application needs to count creations of various types of objects. The application would implement Events and sub-Events similar to the following:

Event creations = listener.lookupEvent(PCHEventClass.USER, "creations");
Event documentCreations = creations.lookupEvent("created documents", true);
Event folderCreations = creations.lookupEvent("created folders", true);

Assuming that these definitions represent all of the possible types of object creation operations, the application would never actually need to use the creations Event object directly. In addition, the pointer to the creations Event object could be discarded by the application because each time a document is created, the recordEvent method of the documentCreations Event object is called, and each time a folder is created, the recordEvent method of the folderCreations Event object is called. This implementation causes the total number of creations performed to be automatically recorded in the creations Event counter, as well as provides the ability to drill down in a Manager to see the number of each type of creation that has been performed.

The auto-increment function is recursive. If the parent of a sub-Event is also a sub-Event that has been configured to auto-increment the parent Event counter, then all three Event counters would be incremented by a single call to recordEvent.