This document describes how to ensure that your custom probe metrics and alarms appear under the correct device in USM.
A brief introduction to the NIS2 data model
The NIS2 (also sometimes called TNT2) data model was created with several goals in mind:
- Create a central database containing descriptions of every metric that the probes collect.
- Create a central inventory of devices being monitored
- Create a central inventory of components of the devices being monitored (disks, network interfaces, etc.)
- Allow localization of metrics (descriptions and metrics).
The NIS2 data model consists of three basic types:
- A device is an IP addressable system. A device entry is implicitly created when a configuration item is created.
- A configuration item (CI) is a component of an IP addressable system. (A disk for example.)
- A ‘metric’ is data that the probe collects that is associated with a CI. (For example, free space on a disk.)
Configuration Items and Metrics
Every alarm and QoS metric should be associated with a NIS2 CI and metric ID so that USM can show it in the correct device view.
- A CI (configuration Item) represents the component being monitored. The component is intended to be a physical element (like a disk). Each CI must be associated with an IP addressable system – this is one of the limitations of the NIS2 data model. The probe must set the following three values when a CI is created with the Nimsoft SDK.
1.1. A CI type identifier that specifies the type of component. This is a dotted decimal representation (for example: 1.1) with an English text representation stored in the database (1.1 = “System”.”Disk”). The dotted decimal representation is localized. The localized text is contained in properties files that are shipped with the WASP and can also be updated separately using the wasp_language_pack package. The CI type IDs are defined in the CM_CONFIGURATION_ITEM_DEFINITION table.
1.2. A CI name that represents the name of the component being monitored (for example, the name of a disk or Ethernet interface: “eth0”).
1.3. A IP Address to associate with the CI, This maybe the IP address of the local system being monitored, or the IP Address of a remote device.
2. A metric type ID represents the kind of measurement being collected. This ID is a single integer but is typically referenced using its fully-qualified path including the CI type, where it is the number after the colon (for example, the full path of 1.1:12 contains the CI type of 1.1 plus the metric ID of 12, where the combination defines a unique kind of metric that can be collected: “System”.”Disk”.”Disk Free”). The metric type ID includes the metric unit, for example: 1.1:12 = “System”.”Disk”.”Disk Free” reported in GB and 1.1:13 = “System”.”Disk”.”Disk Free” reported in MB. The metric type IDs are defined in the CM_CONFIGURATION_ITEM_METRIC_DEFINITION table and units are defined in the CM_METRIC_UNIT table.
Creating CIs that represent the components being monitored is the substantial change required to use the NIS2 model. There are many CIs defined by Nimsoft in the CM_CONFIGURATION_ITEM_DEFINTION table of the NIS2 DB (the Nimosft database usually named NimsoftSLM). Custom probe writers should use one of the provided CI definitions if one is applicable. If no existing CI definition can be used, a CI starting with 9 (“Private”) may be used without contacting Nimsoft, or a range within the “Enterprise” or “Vendor” address spaces can be allocated through Nimsoft support or engineering. Allocating a range whithin the “Enterprise” or “Vendor” address space is not recommended to avoid collisions in the “Private” address space (this is applicable in the case where two NMS environments need to be brought together – for example, a company merger where both companies are using Nimsoft NMS product). Any additions to the CM_CONFIGURATION_ITEM_DEFINITION table (other than within the “Private” space) that are not coordinated through Nimsoft support or engineering maybe overwritten during a product upgrade.
How it all comes together in USM
The SDK creates files in the niscache directory (under the Nimsoft installation directory) that represent devices, configuration items and metrics as a side effect of calling the CI functions (ciOpenRemoteDevice) and using the ciAlarm and/or ciBindQoS functions. The discovery server periodically looks for these files and creates database entries based on the file content from each robot. QoS messages and alarms contain (in the message header) two new properties: dev_id (a link to a device) and met_id (a link to the metric). USM associates the alarms and metrics with the appropriate device based on these properties. Probe code must be modified to use the new API calls that create NIS2 components and link alarms and QoS messages that’s probes produce with those components.
Probes need to follow the genral process outlined below in oirder to subit QoS messages and/or alarms that will be properly linked to USM:
- Create a CI (Configuration Item) that represents the component being monitored.
- Link the CI and metric type ID to a QoS metric and/or alarm that is being delivered.
- Post the QoS metric and/or alarm.
- Unlink the CI and metric to free internal SDK resources.
C SDK Code
CIHANDLE *h; /* Create the CI and the device for a remote host being monitored */ h = ciOpenRemoteDevice(<CI type>, <hostname or IP Address>, <CI name>) /* or, create the CI and the device for the local system being monitored */ /* h = ciOpenLocalDevice(<CI type,<CI name>) */ /* Use the new ciAlarm function to send an alarm associated with the CI device created above */ ciAlarm(h,<CI metric type>,...) /*Associate the given QOSHANDLE (pointer to a QoS that has been created [code not shown */ ciBindQoS(h,<CI metric type>,<QOSHANDLE>,...) /* Free the CI */ ciClose(h)
Other code examples are in the attached PDF.