DOCA Telemetry Utils
This page
provides instructions on the usage of the doca_telemetry_utils tool
.
Supported hardware is NVIDIA® BlueField®-3, NVIDIA® ConnectX®-7, and above.
The doca_telemetry_utils tool
can be used to display all the available counters, and to generate counter IDs which can be used in other DOCA Tools. It also can get the counter type and settings from a given counter ID, and to inform whether this counter is available on the required hardware.
This tool simplifies counter management, making it easier to identify, configure, and verify counter support for specific devices.
doca_telemetry_utils relies on the fwctl driver and, therefore, probing hardware support will fail if run simultaneously with other tools or services that also utilize this driver.
The fwctl driver must be installed on the host:
OS | Commands |
Deb-based 1 |
|
RPM-based |
|
On Ubuntu 20.04, the
fwctldriver is not loaded automatically upon system startup. To load it, run the commandmodprobe mlx5_fwctlafter every reboot.
Installing DOCA Telemetry Utils
To install doca_telemetry_utils:
On deb-based distros , run:
sudoapt-getinstalldoca-telemetry-utilsOn RPM-based distros, run:
sudodnfinstalldoca-telemetry-utils
The doca_telemetry_utils tool can be used with either a counter name or a counter data ID.
Usage with Counter Name
When providing a counter name, doca_telemetry_utils displays the associated data ID and additional details:
The following is an example of running with the counter named global_icmc_hit:
$ doca_telemetry_utils global_icmc_hit
Data ID: 0x1180000200000000
Name: global_icmc_hit
Unit: ICMC
For counters requiring arguments, running the tool with only the counter name displays the options needed.
Running with port_rx_bytes:
[fill_data_id] Per-port counter 0x10200001 (port_rx_bytes) needs exactly 1 argument (local_port), 0 given.
In this case, you must provide the required argument(s) and re-run the command.
Example of specifying the argument local_port:
$ doca_telemetry_utils port_rx_bytes 0
Data ID: 0x1020000100000000
Name: port_rx_bytes
Unit: RX_PORT
local_port: 0
Usage with Data ID
When providing a data ID, doca_telemetry_utils displays the counter name and other details:
Example of running with data ID 0x1180000200000000:
$ doca_telemetry_utils 0x1180000200000000
Data ID: 0x1180000200000000
Name: global_icmc_hit
Unit: ICMC
Checking Counter Support on a Device
To check whether a specific counter is supported by a particular device using the device's PCIe address.
To check if the global_icmc_hit counter is supported on device 08:00.0:
$ doca_telemetry_utils 08:00.0 0x1180000200000000
Data ID: 0x1180000200000000
Name: global_icmc_hit
Unit: ICMC
Data ID 0x1180000200000000 is supported on device 08:00.0
To run doca_telemetry_utils:
$ doca_telemetry_utils -h
Usage:
Name to Data ID:
doca_telemetry_utils [<device PCI>] <name> [relevant properties]
• To get the options for 'relevant properties' run with 'name' alone.
Data ID to name:
doca_telemetry_utils [<device PCI>] <DATA_ID>
• If the optional argument <device PCI> is provided, this device will be tested for support of this counter.
• Run with option 'get-counters' to get all the available names.
-h, --help: Show this help message.
Examples:
Show all available counters:
doca_telemetry_utils get-counters
Name to data ID with relevant options:
doca_telemetry_utils port_rx_bytes 0
Name to Data ID with device PCIe:
doca_telemetry_utils 08:00.0 port_rx_bytes 0
Data ID to name:
doca_telemetry_utils 0x1020000100000000
Data ID to Name with device PCIe:
doca_telemetry_utils 08:00.0 0x1020000100000000