Creating Objects to Gather Performance Data
Once a Listener object has been instantiated, the application will begin to automatically record various system information, such as CPU load, disk and network I/O, as well as communications from connected Managers. The application may expose its performance data using three different types of objects:
- Events - Event objects are either created at the top level of the Listener or logically grouped as subordinates in a Container object using the lookupEvent constructor. In addition, sub-Events can be created under an event. For more information about creating Event objects and recording Events, see Recording Events.
- Accumulators - Accumulator objects are always created as subordinates of Events using the lookupAccumulator constructor.
- Meters - Meter objects are either created at the top level of the Listener or logically grouped as subordinates in a Container object using the lookupMeter constructor.
In addition to these objects, Custom Messages are created at the top level of the Listener and are communicated the moment that recordCustomMessage is called.
Event and Meter objects may either be created at the top level of the Listener or logically grouped as subordinates in a Container object (which is always created at the top level of the Listener using the lookupContainer constructor). They may be created using the lookupEvent or lookupMeter constructors. Accumulator objects are always created as subordinates of Events using the lookupAccumulator constructor.
The lookupObjectType methods
will create the appropriate object only when that object does not
already exist. If the object already exists, the existing object
is returned. In addition, the application should not call delete
on any objects returned by these methods.
Naming and Locating Objects in the Listener
The application creates each of these object types by specifying a unique name for the object which is assumed to be related to a concept or operation in the application, such as a counter for "Documents Created". The name may be specified as a Unicode string of any sequence of printable characters, excluding the newline character.
Once
an object has been created, a pointer to the underlying object is
available for the lifetime of the Listener. Internally, hash tables
are used to map the unique names specified at object creation time
to the actual created objects. By calling the lookupObjectType constructor
method and passing the same arguments as when an object was created,
the application may obtain a pointer to the desired object whenever
necessary. Therefore, the application should not maintain a separate
lookup table. However, the application should retain a copy of
the returned pointers and reuse them to reduce the overhead of
performing the lookup operation. Depending on the structure of the
application, this might be accomplished through the use of static
member variables to achieve the equivalent of global variables,
or by adding new member variables to objects associated with operations
within the application.