This topic describes how to extend IBM Director to support
additional resource monitors.
Subtopics
Related topics
Related sample code
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.
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:
-
Be located in the directory where the agent is installed
-
Be named using the convention monxxxxx.dll, where xxxxx is
1-5 alphanumeric characters that uniquely identify the file
-
Define and export the following entry points:
InitNodes, TermNodes, GetNodeList,
FreeNodeList, GetNodeAttributes,
FreeNodeAttributes, NodeConnect,
NodeDisconnect, NodePulse, NodeGetValue,
NodeFreeValue, GetThresholdCount, GetThresholdPath,
FreeThresholdPath
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:
-
A DLL source file with the following entry points implemented:
-
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.
-
TermNodes
-
Performs any cleanup required for library termination.
The monitor agent calls this function once when it is about to unload the
monitor library.
-
GetNodeList
-
Provides a pointer to a list of the dynamic nodes available
under the specified node of the monitor tree.
-
FreeNodeList
-
Performs any cleanup of the passed-in memory reference
returned from a GetNodeList call.
-
NodeConnect
-
Provides to the monitor agent a numeric handle into this monitor library.
After a valid handle has been returned, the attribute
node starts receiving NodePulse calls and the monitor agent uses the
handle to call GetNodeAttributes and NodeGetValue.
Initialization functions specific to a given monitor attribute can be performed
during this call.
-
NodeDisconnect
-
Performs any cleanup of resources associated with an attribute
node handle and invalidates the handle.
-
GetNodeAttributes
-
Specifies monitor parameters (or meta-data) that tell
the monitor agent how data is to be collected and displayed. This call
is received once per monitor attribute node after
the monitor agent successfully calls NodeConnect and acquires a handle.
-
FreeNodeAttributes
-
Performs any cleanup of the passed-in memory reference
returned from a GetNodeAttributes call.
-
GetThresholdCount
-
Returns the number of server-based Default Thresholds that the Monitor
Extension wishes to be set.
-
GetThresholdPath
-
Returns the complete programmatic or GUI/NLS path that the Default Threshold
should be set upon.
-
FreeThresholdPath
-
Performs any cleanup of the passed-in memory reference return from a
GetThresholdPath call.
-
NodePulse
-
Performs periodic processing (such as data collection
or averaging) required by a monitor attribute node. For each monitor attribute
node for which the monitor agent has acquired a handle, one or more calls
to NodePulse are made before each call to NodeGetValue.
The interval between
these calls is determined by the base_pulse parameter, which is
returned by the call
to GetNodeAttributes.
Pulses are received until the handle is invalidated
by the monitor agent calling NodeDisconnect to release the monitored attribute
node or until the monitor library indicates that the handle is incorrect.
-
NodeGetValue
-
Reports the current value of the monitor attribute node.
The frequency of calls is determined by the pulses_per_data parameter,
which is returned
by the call to GetNodeAttributes.
This call does very little
processing other than looking up the current data point value to return.
Any data gathering and processing should occur in the NodePulse call.
-
NodeFreeValue
-
Performs any cleanup of the passed-in memory reference
returned from a NodeGetValue call.
-
The source file should include
inc\mon_sdk.h,
which defines the
entry points, data structures, and constants for communicating monitor parameters
and data values to the monitor agent.
-
A module definition file that names the library and exports
its entry points.
-
A makefile that builds the DLL.
-
An entry in
inc\monitors.ini
on each client that maps your monitor
library name to a presentable string.
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. |
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
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
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. |
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
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. |
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. |