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.
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.
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);
NOTE 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.
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.