UFM Telemetry can expose an http or https endpoint to allow simple and effective integration with monitoring systems that work in poll mode and support Prometheus, CSV, or JSON data formats. The endpoint provides only the last data sample. The user cannot obtain statistics for time points in the past.
An http endpoint provides data in Prometheus format by default. It also supports JSON and CSV formats. The user can request the desired format using a URL prefix, as shown in the table below.
|Data Format||URL Prefix|
An http endpoint can provide all sampled data using the default
/metrics URL. The filtering functionality described in the Cset/Fset Filtering section is also supported. To use it place
<name>.fset file in appropriate folders. This folder should be stated in configuration file. See section "Configuring Data Polling Endpoint" for more details.
The Extended counter set filtering, as described below, presents an alternative approach to filtering functionality by enabling counters and field selection.
A filter file name is included in the URL to request that the data be filtered through the particular
.fset/.xcset file the user intends. For example, if there are two filter files named
name2.cset, then URLs
/cset/name1 ) and
/cset/name2) can be used to get filtered output described in these files accordingly.
The URL prefixes
/xcet can also be used to specify which filter file is meant.
Folder Parameter in Configuration File
|If the |
If a URL prefix is not specified, then the filter file will be searched under both cset and fset folders. If they both have files with the same names, then both filters will be applied.
Extended Counter Set Filtering
The http server provides an optional Extended counter set (
xcset) selection mechanism in addition to the counter set (
cset) and field set (
fset) filtering. The Extended Counterset allows the user to generate an output record which contains data from both ‘counters‘ and ‘event’ data records with the same index, which in the context of UFM Telemetry is generally the guid/port_num. To define an extended counter set, a file or group of files with the .
xcset extension must be placed in its designated directory or adjacent to existing field or counter sets.
Each line of the file may contain:
- Selection of a counter with an optional alias in the format “
- Selection of a type’s field with an optional alias in the format “
- Reference to another file to be included “
Extended counter set files are searched for in the same directory as the source xcset.
Aliases are not mandatory, but if provided, they are used to name the selected counter or field in the output. Empty lines and comments that begin with the "#" sign are disregarded.
URL Prefixes Priority
URL prefixes can be used to manipulate data output. It is important to use the prefixes in the correct order as they have assigned priorities. The table below shows URL prefixes priority assignments with examples:
Used to show labels from metadata files
Used to specify output format
Used to specify which type of filer file should be applied
Configuring Data Polling Endpoint
To configure the Prometheus endpoint, the keys listed below need to be set in the
There are several options related to configuring the HTTP polling endpoint. The key
plugin_env_PROMETHEUS_ENDPOINT is used to configure the IP interface for endpoint binding. The “0.0.0.0” part in the setting above means that any of the host's valid IP addresses can be used. Note that the user can also specify the host's IP address explicitly.
plugin_env_PROMETHEUS_ENDPOINT key also configures the data transport. For regular HTTP, prefix to
http. To send over a TLS connection, set the prefix to
https, set the above mandatory parameters (keys), and select the existing security keys as follows.
A DH (key exchange protoon) file can also be specified if needed as follows:
There are several options that allow configuring metadata. The file containing the labels used in Prometheus generation is set as follows:
The user can create the metadata file upon system setup or use a script to generate it automatically via script, using the following parameter:
In the above example, the script generates metadata from
/var/log/ibdiagnet2.ibnetdiscover. If the user wishes to create the label file manually, the above option should be commented out to prevent periodic overwriting of the content of the metadata file.
By default, the Prometheus endpoint provides statistics with the collection timestamps. The user can decide whether counter values will be passed with or without timestamps by setting the plugin_env_PROMETHEUS_SHOW_TIMESTAMPS parameter to T (true) or F (false), respectively. For example, to send counter values without timestamps, set the parameter as follows:
To use data filters folders with counter set, field sets, and extended counter sets, the directories where the files are stored should be configured as follows:
Any parameters not explicitly documented should not be changed and should be considered read-only.
For use cases such as UFM Enterprise or UFM Cyber AI where the network topology is known, a human-readable name can be presented based on the GUID.
For integration with third-party applications, labels which are more human-readable may be generated using a labels metadata file, as described below.
Prometheus Label Generation
To generate custom labels, a file containing key-value pairs is used. When the keys are matched, the key-value pairs added to the Prometheus labels are generated.
The following is an example of the format of a labels metadata file:
The following is an example of the generated Prometheus output:
To enable this functionality, the following additional keys need to be configured:
To test, the
curl command can be used as follows: