DOCA DPA Statistics Tool

Introduction

DOCA dpa-statistics is a CLI tool which allows users to monitor and obtain statistics on thread execution per running DPA process and thread. The tool is used to expose information about the running DPA processes and threads and to collect statistics on DPA thread performance.

The tool presents performance information for running DPA threads, including the number of cycles and instructions executed in a time period. The tool enables initiating and stopping collection of statistics and displaying the data collected per thread.

The process ID output of the dpa-ps tool may be used as the input parameter for the dpa-statistics tool.

This tool is supported for NVIDIA® BlueField®-3 only.

Collecting Performance Statistics Data

The command collect works on four mutually exclusive modes:

Enable mode – start collecting performance data
Disable mode – stop collecting performance data
Timeout mode – start collecting, wait with a timeout, stop collect and print info. User could break the wait with Ctrl-C command and then the timeout will be canceled and tool will disable statistics collection and prints the info with the actual time of the collect operation.
Infinite mode – no special flags. Same as timeout mode but with infinite timeout. The tool awaits the Ctrl-C command to stop.

The following table lists the collect command's flags and arguments:

Short Option	Long Option	Description
`-h`	`--help`	Help information
`-d`	`--device`	Device interface name (MST/RDMA)
`-p`	`--process-id`	Hexadecimal process ID for filtering This flag indicates a specific command for the command to operate on. Otherwise, statistics are collected from all processes.
`-i`	`--suppress-header-info`	Suppress print header info
`-n`	`--enable`	Enable collect info
`-o`	`--disable`	Disable collect info
`-t`	`--timeout`	Enable collect, wait with timeout, disable collect and print info Timeout value is in milliseconds. Examples for inputting timeout value: 45 – 45 milliseconds 45.55 – 45 milliseconds and 550,000 nanoseconds .0005 – 500 nanoseconds 45m55n – 45 milliseconds and 55 nanoseconds 66n – 66 nanoseconds
`-r`	`--reset`	Reset counters before operation starting collect operation

Presenting Statistics List

Presenting performance statistics is applicable after initiating data collection.

The following table lists the show command's flags and arguments:

Short Option	Long Option	Description
`-h`	`--help`	Help information
`-d`	`--device`	Device interface name (MST/RDMA)
`-p`	`--process-id`	Hexadecimal process ID for filtering
`-i`	`--suppress-header-info`	Suppress print header info

Output example:

$ sudo ./dpa-statistics show -d mlx5_0 -p 1
ProcessID    Process Name
    ThreadID    Cycles             Instruction        Time               Executions         Thread Name
1            PROCESS_1
    3           266268             18193              164                41                 EH_1_0_0
    4           411571             32727              252                47                 EH_1_1_1

Where:

ProcessID – The dpa_process_object_id to which the thread belongs
Process Name – The dpa_process_name to which the thread belongs
ThreadID – DPA thread object ID
Cycles – Total EU cycles the thread used
Instruction – Total number of instructions the thread executed
Time – Total time in ticks the thread was active
Executions – Total number of thread invocations
Thread Name – The dpa_thread_name

Examples

Example of collect in infinite mode for process 0 with suppress header info:

$ sudo ./dpa-statistics collect -d mlx5_0 -p 0 -i
...^C
Data collected for 4606 milliseconds 0 nanoseconds
0           PROCESS_0
    5           223964             13754              140                31         EH_0_5_5
    6           190130             13754              114                31         EH_0_6_6

Example of collect in timeout mode with a timeout of 1 second and half a millisecond.

$ sudo ./dpa-statistics collect -d mlx5_0 -t 1000.500
Data collected for 1000 milliseconds 500000 nanoseconds
ProcessID    Process Name
    ThreadID    Cycles             Instruction        Time               Executions         Thread Name
0            PROCESS_0
    5           223964             13754              140                31                 EH_0_5_5
    6           190130             13754              114                31                 EH_0_6_6
1            PROCESS_1
    3           266268             18193              164                41                 EH_1_3_3
    4           411571             32727              252                47                 EH_1_4_4
2            PROCESS_2
3            PROCESS_3
    0           223205             13754              137                31                 EH_3_0_0
    1           189896             13754              113                31                 EH_3_1_1
    2           191796             13754              117                31                 EH_3_2_2
4            PROCESS_4

Example of enabling statistics collection with reset of counters.
```
$ sudo ./dpa-statistics collect -d mlx5_0 -n -r
```

Example of disabling statistics collection.

$ sudo ./dpa-statistics collect -d mlx5_0 -o

Known Limitations

Reading large statistics counter blocks takes a long time
The dpa-ps and dpa-statistics tools cannot be run at the same time on the same device

Last updated: May 27, 2026