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", 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.

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(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.

Auto-incrementing Parent Event Counters

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.