DOCA Telemetry Utils

This document provides instructions on the usage of the doca-telemetry-utils tool.

Introduction

DOCA Telemetry Utils can be used to display all available counters and to generate counter IDs which can be used in other DOCA Tools.

Prerequisites

As a prerequisite, need to have fwctl driver installed.

To install the fwctl driver (for host only, for DPU it's already installed), search for a package with "fwctl" and install the package you find.
On deb-based distros, use apt-cache search fwctland for RPM-based distros use dnf search fwctl

On Ubuntu 20.04 the fwctl driver is not loaded automatically, and one needs to modprobe mlx5_fwctl after every reboot.

Installing DOCA Telemetry Utils

To install doca-telemetry-utils:

On deb-based distros, run:

sudo apt-get install doca-telemetry-utils

On RPM-based distros, run:

sudo dnf install doca-telemetry-utils

Description

Doca-telemetry-utils can be used with counter data ID or counter name:

When providing the name, doca-telemetry-utils shows the data ID with further information:
Example output when running with Name global_icmc_hit:
```
Data ID: 0x1180000200000000
Name: global_icmc_hit
Unit: ICMC
```
If the counter has relevant properties, running with the Name alone will show the options. Example output when running with Name port_rx_bytes:
[fill_data_id] Per-port counter 0x10200001 (port_rx_bytes) needs exactly 1 argument (local_port), 0 given.
then, you can use the options and re-run with it. Example output:
Data ID: 0x1020000100000000 Name: port_rx_bytes Unit: RX_PORT local_port: 0
When providing the data ID, doca-telemetry-utils shows the counter name with further information:
Example output when running with data ID 0x1180000200000000:
```
Data ID: 0x1180000200000000
Name: global_icmc_hit
Unit: ICMC
```

If you want to check if the counter is supported by the device, you may use doca-telemetry-utils with <device PCI>.

For example, checking if global_icmc_hit counter is supported on device 08:00.0 will give the following output:

Data ID: 0x1180000200000000
Name: global_icmc_hit
Unit: ICMC
Data ID 0x1180000200000000 is supported on device 08:00.0

Execution

To run doca-telemetry-utils:

Usage: doca_telemetry-utils [DOCA Flags] [Program Args]
DOCA Flags:
  -h, --help                 Print a help synopsis

Program Args:
	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>

[<device PCI>] - optional argument.
	* 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.

Name to Data ID example:

doca_telemetry_utils port_rx_bytes

Name to Data ID (with "relevant options") example:

doca_telemetry_utils port_rx_bytes 0

Name to Data ID with <device PCI> example:

doca_telemetry_utils 08:00.0 port_rx_bytes 0

Data ID to Name example:

doca_telemetry_utils 0x1020000100000000

Data ID to Name with <device PCI> example:

doca_telemetry_utils 08:00.0 0x1020000100000000

Last updated: January 27, 2025