Generic Metrics import
The Generic Metrics Collector imports locally stored text files containing metric data. It can also be used to import metrics data from a third-party source if the metric data is converted to input files that meet file format requirements.
To configure generic metrics import
1. Log in to the UI as admin.
2. Choose Configure > All Settings > Customize > General Settings. The General Settings screen appears, which includes the Polling and Metrics Collection section.
If set to Active, the Generic Metrics Collector scans an input directory for formatted text files containing metric data. The frequency with which the input directory is scanned is determined by the user-configurable collection interval. When valid input files are found, metrics data is imported into NetIM and associated with interfaces or devices in the topology.
Do not use the SNMP MIB Poller and Generic Metrics Collector to collect the same metric data for the same device or interface.
3. To use the Generic Metrics Collector feature, enable the Active flag by doing the following:
– Determine a naming convention for the input files. All input files must have the same file extension. By default, the Generic Metrics Collector recognizes a file extension of mtr. If you use a different file extension you must configure the Generic Metrics Collector to recognize your file extension by setting the appropriate regular expression for filename matching.
– Set the collection interval.
– Convert metrics data to the required file format. Repeat as necessary.
– Copy the properly named and formatted files to the input directory shown in the Polling and Metrics Collection settings. Repeat as necessary.
Generic Metrics Collector best practices and file formatting requirements
The following sections describe the best practices for file naming and working with metric files, and consist of the following topics:
Rules for the naming and handling of Generic Metrics files
• At every time interval that an external mechanism generates metric data, such as every five minutes, the mechanism should copy one or more .mtr files to the Generic Metrics Collector’s input directory. There might be several files per interval, each containing data from a different network device or set of devices. The Generic Metrics Collector processes the .mtr files in the input directory at a configured interval and then appends “.imported” to each filename to prevent the file from being imported again.
• Each .mtr file must be named uniquely with a timestamp or increasing sequence number.
– On the first interval, the files might be named:
DeviceOne001.mtr
DeviceTwo001.mtr
DeviceGroupA001.mtr
DeviceGroupB001.mtr
– On the next interval, the files might be named:
DeviceOne002.mtr
DeviceTwo002.mtr
DeviceGroupA002.mtr
DeviceGroupB002.mtr
• Do not duplicate data within a file, or in more than one file.
• Do not move the same file to the input directory more than once.
Rules for correct formatting of Generic Metrics files
Each .mtr file must be divided into the three logical sections listed in the following table.
Section | Required number |
Metric Sample Data Headers | One or more |
Target Info Header | One |
Metric Samples | Zero or more |
Metric sample data headers
Metric sample data headers define the metric class and the metric fields that are provided for each sample.
Note the following:
• One or more such metric headers can be defined so samples for one or more metric classes can be present in a single file.
• Each metric sample header is defined on a separate line.
• A line that defines a metric sample data header is identified using the start marker [SampleDataHeader]
• This marker is immediately followed by the name (identifier) of the header, in the format [name=X]. This is then followed by name of the metric class which it defines, in the format [metricClass=Y]. See Metric Classes.
• The field names of the header fields are then listed following the metric class name.
• The order in which the field names are listed on this line is the order in which the sample data fields in each sample are output.
• The field names should exactly match the field names defined in the respective .hdr file for that metric class in NetIM but can be listed in any order. The .hdr files are in the NetIM installation directory in the following location: <install dir>/lib/xml/res/metrics.
• Header files for user-defined metrics are in the NetIM installation directory in the following location: <install dir>/lib/xml/res/custommetrics.
• A subset of the field names defined in the .hdr file is also allowed. For example, if the .hdr file for a particular metric class contains five fields, only three may be used/listed in the sample header for the metric class in the metric data file.
Metric classes
Commonly used metric classes include the following:
• COS_DROPS
• COS_UTIL
• CPU_UTIL
• DEV_STATUS
• IFC_UTIL
• INTERFACE_AVAILABILITY
• INTERFACE_ERRORS
• INTERFACE_STATUS
• SERVER_DISK_USAGE
• SERVER_SW_RUN_PERF
You can find additional metric classes by looking at the Header Name property in each of the .hdr files in the <install_dir> dir>/lib/xml/res/metrics directory.
Target info header
The target info header is a single line in the file that lists the names of the target fields that will be output for each metric sample and the order in which they will be output.
Note the following:
• The target header line is identified using the start marker [TargetInfoHeader].
• The order in which the field names are listed on this line is the order in which the target information fields in each sample are output.
• Several target fields are supported so that metrics can be accurately associated with the parent that contains them, as shown in the following table:
Target field name | Required? | Description |
SYSNAME | Yes | The sysname of the device the metric pertains to. |
IFINDEX | Yes* | The ifIndex of the interface the metric pertains to. |
IFDESCR | Yes* | The ifDescr of the interface the metric pertains to. |
IFNAME | Yes* | The ifName of the interface the metric pertains to. |
HEADERNAME | Yes | Name of the header for this sample. This is used to identify the header that describes the sample data. |
(*) If importing an interface level metric, at least one of the following is required: IFINDEX, IFDESCR, or IFNAME.
Metric samples
Each metric sample must be on a separate line in the following format:
[TI]<target information data>[SI][SD]<sample data>
Note the following:
• The Target Information section consists of comma separated values that indicate the entity to which the sample belongs. This section starts with [TI] delimiter. The values are interpreted using the target header defined in the metric data file with the [TargetInfoHeader] marker.
• An [SI] delimiter needs to be present between the Target Information section and the Sample Data section.
• The Sample Data section consists of the actual sample data, containing a list of comma separated values. The sample values are interpreted using the sample header defined in the metric data file with the [SampleDataHeader] marker for the metric class of the sample. This section starts with [SD] delimiter.
Example metric file
This following is an example of a valid input file for the Generic Metrics Collector:
[SampleDataHeader][name=H1][metricClass=CPU_UTIL]timestamp,cpuIndex,cpuName,cpuUtilType,cpuUtil
[TargetInfoHeader]HEADERNAME,SYSNAME
[TI]H1,P1.lab.rvbd.com[SI][SD]1329235965717,2,,cpmCPUTotal1minRev,73.52
[TI]H1,P1.lab.rvbd.com[SI][SD]1329235965717,2,,cpmCPUTotal5minRev,73.52
leDataHeader] marker for the metric class of the sample. This section starts with [SD] delimiter.