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",
NULL, NULL);
Event *toplevelEvent = listener->lookupEvent(eventClass, "eventName",
[optional] includeParent);
or as a subordinate to a Container:
Container *eventContainer = listener->lookupContainer("containerName");
Event *subordinateEvent = eventContainer->lookupEvent(eventClass,
"eventName", [optional] includeParent);
or as a sub-Event (subordinate to another Event):
Event *subEvent = subordinateEvent->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 member function.
The eventClass parameter of the constructor is an EventClass
enumeration constant that specifies the class of the Event. (This parameter
is not specified when creating a sub-Event of another Event object because the
event class of the sub-Event must be the same as that employed by the parent
Event object.) The application may implement an Event as class RPC
to record top level client requests, or as class 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
.
The eventName is a string which provides the name for the Event. The 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. The includeParent parameter is an optional Boolean value (default is false), which indicates whether the recordEvent member function 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(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 member function 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(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 member function of the documentCreations
Event object is called, and each time a folder is created, the recordEvent function
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.