IBM Director Resource Monitor Agent extensions
The IBM Director Resource Monitor
Agent is an extendable service for collecting and displaying real-time
data on system resources. The monitor agent (TWGMonit.exe) executes on
the system being monitored and 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 needs
only to provide data to the monitor agent, which handles the 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 are
quantitative monitors in that they track system attributes or components
that are measured in terms of some numerical value. Numeric attributes
can be used to monitor resource utilization, such as CPU, DASD or memory.
In this case, the quantity being tracked is a percentage, and values can
range between zero and one hundred. String monitor attributes are qualitative
monitors in that they deal with non-numeric qualities of the systems and
components being monitored. String attributes can be used to monitor the
state of devices, such as "off-line", "online", or "busy".
Monitor library discovery
When the monitor agent is started,
it searches for monitor libraries in its current directory. To be discovered
by the monitor agent, a monitor library must:
-
exist in the directory where the agent is installed
-
be named MONXXXXX.DLL, where XXXXX is a one to five alphanumeric
monitor name suffix that must be distinct from any other installed monitor
library
-
define and export the following entry points:
InitNodes, TermNodes, GetNodeList, FreeNodeList, GetNodeAttributes,
FreeNodeAttributes, NodeConnect, NodeDisconnect, NodePulse, NodeGetValue,
NodeFreeValue
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
requirements must be met:
-
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 clean up 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 a numeric handle into this monitor library
to the monitor agent. After a valid handle has been returned the attribute
node will start receiving NodePulse calls and the handle will be used by
the monitor agent when calling GetNodeAttributes and NodeGetValue.
Initialization functions specific to a given monitor attribute can be performed
during this call.
NodeDisconnect
Performs any cleanup of resources associated to 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 a handle has been acquired
by the monitor agent calling NodeConnect successfully.
FreeNodeAttributes
Performs any cleanup of the passed-in memory reference
returned from a GetNodeAttributes call.
NodePulse
Performs periodic processing (such as data collection
or averaging) required by a monitor attribute node. For each monitor attribute
node that the monitor agent has acquired a handle for, one or more calls
to NodePulse are made before each NodeGetValue call. The interval between
these calls is determined by the base_pulse parameter 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 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 returned
by the call to GetNodeAttributes. This call should do very little
processing other than looking up the current data point value to return.
Any data gathering/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 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 monitors.ini on each client that maps your monitor
libary name to a presentable string.
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 might vary,
depending on the system's hardware configuration, software configuration,
or other factors. The first job of the monitor library is to determine
if it can provide any 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 MONENTPNT 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:
Returns:
A boolean 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. |
Discovering the available attributes in a monitor
library
The available monitor attributes are
displayed in a tree view by the IBM Director Resource Monitor Console.
This 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 fashion with as many nodes and branches as you need
to make it easy to navigate and understand for the user. As a
user navigates into the IBM Director Agent node on the console, they will see
a branch for each monitor library installed on that individual client or
for the collection of libraries availble on the systems that they have
choosen to monitor. The list of monitor libraries is provided to
the server by the monitor agent by matching up the initialized monitor
libraries to their presentation names located in the monitors.ini file.
If a filename mapping is not found, then the library name without its extension
will be displayed in the console. When the user expands a monitor
library node, the monitor agent will query the library for its nodes or
leaves (attributes) at that level by calling the GetNodeList entry point.
So, the first time the library will be queried by the monitor agent is
for its Level 1 nodes/attributes, since 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 will call FreeNodeList
with the data reference so the monitor library can free the memory it allocated
for the data structure. The get/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 * MONENTPNT GetNodeList( AttributePath MONFAR
*queriedPath)
Provides a pointer to a list of the dynamic nodes available
under the specified node of the monitor tree.
Parameters:
AttributePath - programatic path to node being queried
for its child nodes or leaves
Returns:
AttributeNodeList * - a pointer to a filled-in list of
programatic and displayable nodes or attributes allocated by the monitor
library
void MONENTPNT FreeNodeList( AttributeNodeList MONFAR *pNList)
Frees the referenced pointer to a list of the dynamic
nodes returned by a call to GetNodeList.
Parameters:
AttributeNodeList * - a pointer to a filled-in structure
returned by a call to GetNodeList
Returns:
Connecting to an attribute in a monitor library
A handle to a monitor attribute is
acquired by the monitor agent when the console user wants to monitor, record
or set a threshold range for its value. The handle returned by NodeConnect
call should be a persistent handle or index value maintained by the monitor
library with as much 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, NodePulse and NodeGetValue calls until a NodeDisconnect
call is made on the handle.
BOOL MONENTPNT NodeConnect( AttributePath MONFAR *pAPath, ULONG
MONFAR *key, BYTE MONFAR *dataType)
Provides a numeric handle into this monitor library to
the monitor agent. Initialization functions specific to a given monitor
attribute can be performed during this call.
Parameters:
AttributePath * - pointer to the programatic path representing
a monitor attribute to obtain the handle for
ULONG * - pointer to a 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. |
BYTE * - pointer to the monitor attribute type
Value Range |
Meaning |
DYNAMICNODE_ATTRIBUTE (0x08) |
The monitor attribute is a dynamic
attribute. |
INVALID_ATTRIBUTE (0x00) |
The monitor attribute is incorrect. |
Returns:
A boolean indicating if a valid monitor attribute handle
was returned.
Define Name |
Meaning |
FALSE |
A handle could not be returned
to the specifed 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. |
NodeParms * MONENTPNT GetNodeAttributes( ULONG key)
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 a handle has been acquired
by a successful call to NodeConnect.
Parameters:
ULONG - unsigned long key returned by a call to
NodeConnect()
Value Range |
Meaning |
0x00000000 to 0xFFFFFFFE |
A valid handle into the monitor
library. |
INVALID_HANDLE (0xFFFFFFFF) |
An incorrect handle. |
Returns:
NodeParms * - pointer to a DLL allocated NodeParm
structure or NULL if the handle was incorrect
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 when 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 it's 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 atttribute. A monitor
attribute reports its data value to the monitor agent by returning a completed
NodeData structure on a NodeGetValue call.
ULONG MONENTPNT NodePulse( ULONG key, ULONG time_since_last)
Called for each attribute that the monitor agent has
acquired a handle to, providing the extension DLL time to perform
its periodic processing (such as data collection or averaging.) The
extension DLL must check the time_since_last value or keep track of its
last pulse time to verify that it is time to do its data processsing.
This is required because the pulse time of the agent is determined by the
smallest requested pulse value of all attributes.
Parameters:
ULONG - unsigned long representing a monitor attribute
handle returned by the NodeConnect call
ULONG - unsigned long representing the elapsed time in
msec since the last pulse processing of all attributes
Returns:
The amount of time in msec until the next pulse is needed
NodeData * MONENTPNT NodeGetValue( ULONG key)
Retreives 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:
ULONG - unsigned long representing a monitor attribute
handle returned by the NodeConnect call
Returns:
A completed NodeData struct with a good return code and
valid data set or with a failure return code set.
void MONENTPNT NodeFreeValue( NodeData MONFAR *nd)
Performs any clean up of the memory allocated by a call
to NodeGetValue.
Parameters:
NodeData * - pointer a NodeData struct returned
from a call to NodeGetValue
Returns:
Releasing an attribute in a monitor library
When all of the users have stopped monitoring and recording
an attribute and when the last threshold has been disabled or deleted,
then the monitor agent will call FreeNodeAttributes and then NodeDisconnect
once with the pointer returned by NodeGetAttributes and the handle returned
by the NodeConnect calls so the monitor library can perform any cleanup
of its associated data being maintained for the attribute. The monitor
library will receive no further calls for this monitor attribute after
the NodeDisconnect call unless a user wants to monitor the attribute again,
at which time a NodeConnect call will be made to acquire a new handle to
the attribute.
void MONENTPNT FreeNodeAttributes( NodeParms MONFAR *nParms)
Performs clean up of the DLL allocated memory returned
by a call to GetNodeAttributes.
Parameters:
NodeParms * - pointer to NodeParms structure returned
by a call to GetNodeAttributes
Returns:
BOOL MONENTPNT NodeDisconnect( ULONG key)
Performs any clean up of the persistent data associated
with the handle and invalidates the handle so future calls referencing
it will not be valid.
Parameters:
ULONG - the handle to a monitor attribute returned by
a call to NodeConnect
Returns:
A boolean 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
(usually when the system is being shut down), it issues a termination call
to every monitor library it initialized by calling the TermNodes entry
point. The monitor library should then cleanup any dynamic storage it has
allocated and terminate all processing.
BOOL MONENTPNT TermNodes()
Performs any clean up required for library termination.
The monitor agent calls this function once when it is about to unload the
monitor library.
Parameters:
Returns:
A boolean 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. |
Monitor library constants
Return Values for the rc fields in the _TWG_xxx structs:
RC_OK
- operation was successful
RC_INVALID_CMD
- command not implemented yet
RC_INVALID_PARMS - incorrect number of input parms
RC_INVALID_INPUT - an input
parm was incorrect or NULL
RC_INVALID_VERSION - unsupported struct
version was sent
RC_MEMORY_FAILURE - memory allocation
failed
RC_INVALID_OUTPUT - returned output
is not valid
RC_INVALID_PATH - unknown
path was sent
RC_INVALID_HANDLE - incorrect handle
was sent or returned
RC_INVALID_DATA - returned
struct contains incorrect data
RC_INVALID_TYPE - data
was for an unsupported attribute type
RC_INVALID_TRANSPORT - problems occurred when using
the transport services
RC_NODE_UNAVAILABLE - the specified DynamicNode
is not available, but might be later
RC_INVALID_ID
- incorrect threshold ID was sent or returned
These are the defined Attribute/Node types supported by Monitor DLLs:
INVALID_ATTRIBUTE - the attribute
is a node that cannot be monitored
DYNAMICNODE_ATTRIBUTE - the attribute is a leaf that can
be monitored
This define is used to indicate that a handle could not be acquired or
to invalidate a handle being returned:
INVALID_HANDLE
- specified path could not be resolved to a leaf
The following are the defined data types that can be returned by the NodeData
structure:
INVALID_NODEDATA - the NodeData
does not contain any valid data
DOUBLE_NODEDATA - the
data should be interpreted as a double value
STRING_NODEDATA - the
data should be intrepreted as an offset to a string
The following are the defined types that should be used for exporting the
required Monitor DLL entry points. The type has been defined for
each supported operating system so common code and programming requirements
can be maintained.
MONFAR
- only relavant to Windows 3.x support
MONENTPNT
- properly exports the required monitor library entry points
The following define what versions of the structures being used.
Currently there is only one supported version of each structure.
CURRENT_PATH_VERSION - current
version of the AttributePath structure
CURRENT_NODE_VERSION - current
version of the AttributeNode structure
CURRENT_NODE_LIST_VERSION - current version of the AttributeNodeList
structure
CURRENT_NODEPARMS_VERSION - current version of the NodeParms
structure
CURRENT_NODEDATA_VERSION - current version of the
NodeData structure
Monitor library structures
AttributePath
long size;
- should be set to the total size of the completed structure
BYTE version;
- should be set to CURRENT_PATH_VERSION
char lang[6];
- Compressed Unicode locale in Java format for NLS support
long members;
- number of pathname strings
long offsets[members];
- array of offsets inside struct to each pathname member
BYTE[]
- location of the Compressed Unicode pathname string(s) within the structure
AttributeNode
long size;
- total size of this struct w/ strings
BYTE version;
- should be set to CURRENT_NODE_VERSION
char lang[6];
- Compressed Unicode locale in Java format for NLS support
BYTE isLeaf;
- 0=node and 1=leaves w/ data
BYTE type;
- data type - INVALID_NODEDATA for nodes and DOUBLE_NODEDATA
or STRING_NODEDATA for leaves
long nameOffset;
- offset inside struct to the displayable name
long symNameOffset;
- offset inside struct to the programatic name
BYTE[]
- location of the Compressed Unicode displayable string within the structure
BYTE[]
- location of the Compressed Unicode programatic string within the structure
AttributeNodeList
long size;
- size of this struct w/o nodes (used as the offset location of the
first node)
BYTE version;
- should be set to CURRENT_NODE_LIST_VERSION
long totalSize;
- total size of this struct w/ nodes
long members;
- number of nodes in the list
BYTE[]
- location of the AttributeNode structures within the structure
NodeParms
ULONG size;
- total size of the completed structure
BYTE version;
- should be set to CURRENT_NODEPARMS_VERSION
long rc;
- RC_OK, RC_MEMORY_FAILURE, RC_INVALID_HANDLE or
RC_INVALID_DATA
ULONG base_pulse;
- Maximum time, in milliseconds, between calls to NodePulse
ULONG pulses_per_data;
- Number of NodePulse calls between NodeGetValue calls
ULONG num_recorded;
- Max number of recorded value changes (at least 5 mins worth)
ULONG attrib_flags;
- Flags for attribute (not used and should be 0)
ULONG output_type;
- Output device recommended (not used and should be 0)
ULONG number_data_levels;
- Total number of data levels supported (not used and should be 0)
DataLevelRec *data_levels;
- Pointer to array of data levels (not used and should be NULL)
ULONG units_label_offset;
- Offset in struct to CompUnicode Label for units of measure (optional
and should be 0 if not used)
ULONG value_format_offset;
- Offset in struct to CompUnicode printf format string for value
BYTE[]
- location of the Compressed Unicode units_label string within the structure
BYTE[]
- location of the Compressed Unicode value_format string within the structure
DataLevelRec
ULONG data_count;
- Maximum samples saved before rollup to next level
ULONG count_to_next;
- Number of samples used to make rolled-up value
Node Data
long size;
- should be set to the total size of the completed structure
BYTE version;
- should be set to CURRENT_NODEDATA_VERSION
long rc;
- RC_OK, RC_MEMORY_FAILURE, RC_INVALID_HANDLE or
RC_INVALID_DATA
BYTE dataType;
- INVALID_NODEDATA, DOUBLE_NODEDATA or STRING_NODEDATA
union {
double dValue;
- double value when dataType is DOUBLE_NODEDATA
long strOffset;
- offset inside of this struct to the CompUnicode string when dataType
is STRING_NODEDATA
} data;
BYTE[]
- location of the Compressed Unicode string within the structure if set