DOCA Telemetry Utils

This document provides instructions on the usage of the doca_telemetry_utils tool.

Introduction

The doca_telemetry_utils tool can be used to display all available counters and to generate counter IDs which can be used in other DOCA Tools.

This tool simplifies counter management, making it easier to identify, configure, and verify counter support for specific devices.

Prerequisites

The fwctl driver must be installed on the host:

OS	Commands
Deb-based	Search for the package: apt-cache search fwctl Install the package: sudo apt install <package-name>
RPM-based	Search for the package: dnf search fwctl Install the package: sudo dnf install <package-name>

Commands

Deb-based

Search for the package:
```
apt-cache search fwctl
```
Install the package:
```
sudo apt install <package-name>
```

RPM-based

Search for the package:
```
dnf search fwctl
```
Install the package:
```
sudo dnf install <package-name>
```

We don't have a way to export this macro.

Installing DOCA Telemetry Utils

To install doca_telemetry_utils:

On deb-based distros, run:

Bash

sudo apt-get install doca-telemetry-utils

On RPM-based distros, run:

Bash

sudo dnf install doca-telemetry-utils

Description

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:

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:

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:

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:

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.

Examples:

Name to data ID:
Bash
```
doca_telemetry_utils port_rx_bytes
```
Name to data ID with relevant options:
Bash
```
doca_telemetry_utils port_rx_bytes 0
```

Name to Data ID with device PCIe:

Bash

doca_telemetry_utils 08:00.0 port_rx_bytes 0

Data ID to name:

Bash

doca_telemetry_utils 0x1020000100000000

Data ID to Name with device PCIe:

Bash

doca_telemetry_utils 08:00.0 0x1020000100000000

Last updated: January 27, 2025