Creating Resource Monitor Agent extensions

This topic describes how to extend IBM Director to support additional resource monitors.

Subtopics

Related topics

Related sample code

Understanding Resource Monitor Agent extensions

The IBM Director resource monitor agent (monitor agent) is an extendable service for collecting and displaying real-time data on system resources. The monitor agent (TWGMonit.exe) runs on the system being monitored. It loads the installed monitor libraries on the system by invoking predefined entry points in each library for monitor initialization, data collection, and termination. The monitor library provides data to the monitor agent, which handles communications with the monitor server, routine data collection, recording of data points, threshold conditions, and alert generation.

The monitor agent supports two types of dynamic attributes: Numeric and String. Numeric monitor attributes track system attributes and components and use numerical values to measure the results. String monitor attributes are qualitative monitors that deal with non-numeric qualities of the systems and components being monitored. String attributes can be used to monitor the states of devices, such as off-line, online, or busy.

Monitor library discovery

When a monitor agent is started, it searches for monitor libraries in its current directory. To be discovered by the monitor agent, a monitor library must:

Developing a monitor library

A monitor library is a dynamic link library (DLL) or NetWare load module (NLM) that is loaded by the monitor agent at run-time. To add a new monitor library extension, the following items are required:

Initializing a monitor library

A monitor library can provide any number of monitor attributes to monitor all kinds of system resources. The number of attributes supported by a monitor library on a given system varies according to the system's hardware configuration, software configuration, or other factors. The first task of a monitor library is to determine if it can provide monitor attributes on the system where it is installed. When the monitor agent discovers a monitor library, it issues the InitNodes call to find out if the monitor library is supported on this system.

BOOL APIENTRY InitNodes()
Determines if the monitor library is supported for this system and performs any initialization required by the library. The monitor agent calls this function once after it discovers a monitor library.
Parameters:
none
Returns:
A boolean value indicating if this monitor library is supported on this system.
Define Name Meaning
FALSE The monitor library is not supported on this system or its initialization failed.
TRUE The monitor library has attributes for this system and was initialized successfully.

Retrieving default threshold paths

By supplying default threshold paths and threshold templates to the monitor server, developers can provide a base set of thresholds with their monitor extensions.

ULONG APIENTRY GetThresholdCount()
Provides the number of server-based default thresholds that the extension wants to be created.
Parameters:
none
Returns:
ULONG
The number of default thresholds to set
AttributePath * APIENTRY GetThresholdPath( ULONG index, char *lang)
Provides the zero-based default threshold path for the programmatic path (denoted by lang being a NULL pointer) or the specified GUI/NLS path (denoted by receiving a Java Locale string.)
Parameters:
index
The index of the path to provide
lang
The requested path locale to provide or NULL for the programmatic path
Returns:
AttributePath
The complete attribute path to set the default threshold on
void APIENTRY FreeThresholdPath( AttributePath *pAPath)
Frees the referenced pointer to an attribute path returned by a call to GetThresholdPath
Parameters:
pAPath
A pointer to an attributePath structure returned by a call to GetThresholdPath
Returns:
none

Discovering the available attributes in a monitor library

The available monitor attributes are displayed in a tree view by the IBM Director Resource Monitors console.

A tree view is the conceptual view of how your monitor library nodes and attributes should be laid out. The monitor attributes should be grouped and laid out in a tree format with as many nodes and branches as needed to help the user understand and navigate the structure. When the user applies the Monitors task to an individual system, a branch representing each monitor library installed on the system is displayed. When the user selects a group of systems, a branch representing the collection of available monitor libraries is displayed. The list of monitor libraries is provided to the server by the monitor agent by matching the initialized monitor libraries to their presentation names located in the inc\monitors.ini file. If a filename mapping is not found, the library name without its extension is displayed in the console.

When the user expands a monitor library node, the monitor agent queries the library for its nodes or leaves (attributes) at that level by calling the GetNodeList entry point. The first time the library is queried by the monitor agent is for its Level 1 nodes and attributes, because the monitor agent handles the Level 0 or root queries for the monitor libraries. After the monitor agent has processed the data returned by a GetNodeList call, it calls FreeNodeList with the data reference in order that the monitor library can free the memory it allocated for the data structure. The get and free calls are made back-to-back to each other and can be received at any time between the initialization and termination of a monitor library.

AttributeNodeList * APIENTRY GetNodeList( AttributePath MONFAR *queriedPath)
Provides a pointer to a list of the dynamic nodes available under the specified node of the monitor tree.
Parameters:
queriedPath
Programmatic path to the node being queried for its child nodes or leaves
Returns:
AttributeNodeList *
A pointer to a filled-in list of programmatic and displayable nodes or attributes allocated by the monitor library
void APIENTRY FreeNodeList( AttributeNodeList *pNList)
Frees the referenced pointer to a list of the dynamic nodes returned by a call to GetNodeList
Parameters:
pNList
A pointer to a filled-in AttributeNodeList structure returned by a call to GetNodeList
Returns:
none

Connecting to an attribute in a monitor library

A handle to a monitor attribute is acquired by the monitor agent when the console user attempts to monitor, record, or set a threshold range for its value. The handle returned by the NodeConnect call should be a persistent handle or index value maintained by the monitor library with as many of the AttributePath or meta-data values required until the monitor agent releases the attribute by calling NodeDisconnect. After a valid handle has been acquired, it can be used at any time for the GetNodeAttributes and NodeGetValue calls until a NodeDisconnect call is made on the handle.

BOOL APIENTRY NodeConnect( AttributePath *pAPath, ULONG *key, BYTE *dataType)
Provide to the monitor agent a numeric handle into the monitor library.
Parameters:
pAPath
Pointer to the programmatic AttributePath representing a monitor attribute for which the handle is to be obtained
key
Pointer to an unsigned long to hold the monitor attribute handle or INVALID_HANDLE
Value Range Meaning
0x00000000 to 0xFFFFFFFE A valid handle into the monitor library.
INVALID_HANDLE (0xFFFFFFFF) An incorrect handle.
dataType
Pointer to byte to hold the monitor attribute type or INVALID_ATTRIBUTE
Value Range Meaning
DYNAMICNODE_ATTRIBUTE (0x08) The monitor attribute is a dynamic attribute.
INVALID_ATTRIBUTE (0x00) The monitor attribute is incorrect.
Returns:
A boolean value indicating if a valid monitor attribute handle was returned
Define Name Meaning
FALSE A handle could not be returned to the specified monitor attribute path.  The path is not valid for this monitor library or for this particular system.
TRUE A valid handle was returned for the specified monitor attribute.

Gathering data from an attribute in a monitor library

Periodically the monitor agent polls each monitor attribute handle for its current value. The monitoring process occurs continuously from the time a handle is acquired until it is released. Monitor attributes are polled for data according to the attribute's base_pulse and pulses_per_data parameters. Each attribute receives one or more pulses, or NodePulse calls, before its current value is requested with NodeGetValue. Pulses allow the monitor to perform periodic activities like polling a device for data. The monitor agent issues a NodeGetValue call immediately after the last of pulses_per_data pulses to obtain the next data point from an attribute. A monitor attribute reports its data value to the monitor agent by returning a completed NodeData structure on a NodeGetValue call.

ULONG APIENTRY NodePulse( ULONG key, ULONG time_since_last)
Pulses allow the monitor agent to perform periodic activities, such as, polling a device for data and calculating its new data point value.
Parameters:
key
Unsigned long representing a monitor attribute handle returned by the NodeConnect call
time_since_last
Unsigned long representing the time, in milliseconds, since the last pulse was taken. This value can be less than or greater than the requested base_pulse amount.
Returns:
The amount of time, in milliseconds, until the attribute should be pulsed again.
NodeData * APIENTRY NodeGetValue( ULONG key)
Retrieve the currently cached data for the specified monitor attribute handle. This call should be a lightweight call with any data collection or averaging overhead performed in the NodePulse call.
Parameters:
key
Unsigned long representing a monitor attribute handle returned by the NodeConnect call
Value Range Meaning
0x00000000 to 0xFFFFFFFE A valid handle into the monitor library.
INVALID_HANDLE (0xFFFFFFFF) An incorrect handle.
Returns:
A completed NodeData struct with a good return code and valid data set or with a failure return code set

void APIENTRY NodeFreeValue( NodeData *nd)
Performs cleanup of the memory allocated by a call to NodeGetValue
Parameters:
nd
Pointer a NodeData struct returned from a call to NodeGetValue
Returns:
none

Releasing an attribute in a monitor library

When all users have stopped monitoring and recording an attribute and when the last threshold has been disabled or deleted, the monitor agent calls NodeDisconnect once using the handle returned by the NodeConnect call. Calling NodeDisconnect enables the monitor library to perform a cleanup of the associated data it is maintaining for the attribute. After the NodeDisconnect call is issued, the monitor library receives no further calls for this monitor attribute unless a user wants to monitor the attribute again, at which time a NodeConnect call is made to acquire a new handle to the attribute.

BOOL APIENTRY NodeDisconnect( ULONG key)
Performs any cleanup of the persistent data associated with the handle and invalidates the handle in order that future calls referencing it will not be valid.
Parameters:
key
The handle to a monitor attribute returned by a call to NodeConnect
Returns:
A boolean value indicating if the passed-in monitor attribute handle was released
Define Name Meaning
FALSE The referenced handle was incorrect or already released.
TRUE The handle and its data were released.

Terminating a monitor library

When the monitor agent terminates execution, for example, when the system on which the agent is running is shut down, it issues a termination call to every monitor library it initialized by calling the TermNodes entry point. The monitor library should then clean up any dynamic storage it has allocated and terminate all processing.

BOOL APIENTRY TermNodes()
Performs any cleanup required for library termination. The monitor agent calls this function once when it is about to unload the monitor library.
Parameters:
none
Returns:
A boolean value indicating if this monitor library was terminated
Define Name Meaning
FALSE The monitor library termination failed.  This return code is ignored.
TRUE The monitor library has finished its termination routines.