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 four different categories:
new
operator. In addition, sub-Events may created under
an event. For more information about creating Event objects and recording
Events, see Recording Events.new
operator.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 or via the new
operator. Accumulator objects are always created as subordinates of Events using
the lookupAccumulator constructor. Custom
Messages are always created at the top level of the Listener using the recordCustomMessage
constructor.
The lookupObjectType
member functions 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 functions.
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". Through overloaded
member functions, the name may be specified either as a UTF-8 or Unicode string
(internally translated to UTF-8). The names for any of these objects may consist
of any sequence of printable characters excluding the newline character. In addition, an internal
copy for each string is made and the application does not need not maintain
the pointer once the lookupObjectType
constructor has
returned.
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 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 global variables, or by adding
new member variables to objects associated with operations within the application.