DOCA 遥测诊断

本指南提供关于构建和开发应用程序的说明，这些应用程序需要收集由 NVIDIA® BlueField 和 NVIDIA® ConnectX® 系列网络平台提供的遥测信息。

简介

doca_telemetry_diag 提供对设备上机制的可编程访问，该机制允许对诊断数据（例如，统计数据和计数器）进行采样。doca_telemetry_diag 允许配置诸如所需数据 ID 或采样周期等参数，并以多种格式检索生成的信息。

前提条件

要使用 DOCA 遥测诊断，必须满足以下前提条件

已安装并加载 fwctl 驱动程序（请参阅 NVIDIA MLNX_OFED 文档 v24.07-0.6.1.0 中的说明）

注意

要验证 fwctl 驱动程序是否已成功加载

复制
已复制！

            
            $ ls /sys/class/fwctl/

预期输出

复制
已复制！

            
            fwctl0  fwctl1

如果目录 /sys/class/fwctl 不存在或为空，请按照以下步骤操作

搜索 fwctl 软件包

复制
已复制！

            
            $ apt search fwctl

输出可能指示 fwctl-dkms 或 fwctl-modules。

安装适当的软件包

复制
已复制！

            
            $ sudo apt install fwctl-dkms

或

复制
已复制！

            
            $ sudo apt install fwctl-modules

加载 mlx5_fwctl 模块

复制
已复制！

            
            $ sudo modprobe mlx5_fwctl

确认模块已加载

复制
已复制！

            
            $ lsmod | grep fwctl

预期输出

复制
已复制！

            
            mlx5_fwctl             20480  0
fwctl                  24576  1 mlx5_fwctl
mlx5_core            2211840  2 mlx5_fwctl,mlx5_ib
mlx_compat             20480  17 rdma_cm,ib_ipoib,mlxdevm,nvme,mlxfw,mlx5_fwctl,iw_cm,nvme_core,nvme_fabrics,ib_umad,fwctl,ib_core,rdma_ucm,ib_uverbs,mlx5_ib,ib_cm,mlx5_core

ConnectX-7 的固件版本 28.43.1000 或 BlueField-3 的固件版本 32.43.1000

环境

基于 DOCA 遥测的应用程序可以运行在主机上（ConnectX-7 或 Bluefield-3 及更高版本）或 DPU 目标上（BlueField-3 及更高版本）。

DOCA 遥测只能在 BlueField 配置为 DPU 模式下运行，如BlueField 运行模式中所述。

架构

诊断数据以采样循环缓冲区形式存储在固件中。每个采样代表所有请求的诊断数据 ID 的值及其相应的采样时间戳。

设备和所有权

DOCA 遥测库需要一个 ConnectX/BlueField DOCA 设备来进行采样。可以使用其任何物理功能 (PF) 访问该设备。

注意

如果设置中存在多个设备，则应为每个设备创建一个 doca_telemetry_diag 上下文。

doca_telemetry_diag 被设计为每个设备作为一个单例运行。创建后，doca_telemetry_diag 上下文将接管相关硬件资源的控制权，以防止冲突并确保准确的数据采样。在极少数情况下，所有权可能会被覆盖（例如，如果进程在释放所有权之前崩溃）。

信息

从第二个进程创建上下文时，可以使用 force_ownership 参数。

注意

一旦为一个 PF 强制执行了所有权，则不能被不同的 PF 声明。建议始终使用 PF0 以防止潜在的冲突。

配置阶段

配置

可以配置上下文以匹配应用程序用例。

要了解是否支持某种配置，或者其最小/最大值是多少，请参阅“设备支持”部分。

采样模式

DOCA 遥测诊断库支持以下操作方法

单次采样 - 样本被存储，一旦样本的固件缓冲区被填满，采样就会终止。

信息

如果需要，可以重新启动上下文以收集新样本，直到固件缓冲区被填满，覆盖之前的样本。
重复采样 - 当样本缓冲区被填满时，新样本会覆盖旧样本。

信息

采样持续进行直到上下文停止。
按需 - 设备不收集样本。在每次查询诊断数据时，设备都会提取数据的单个样本。

重复采样模式的注意事项

当将 DOCA 遥测诊断库配置为重复采样时，重要的是要确保固件缓冲区的大小足以处理硬件采样和软件检索之间的数据流。固件缓冲区大小由 log_max_num_samples 属性决定。

确定采样率
- 硬件采样率 - 硬件收集数据的频率（例如，每 100 微秒）
- 软件检索率 - 软件连续检索数据之间的平均时间间隔（例如，每 500 毫秒）
使用以下公式计算 AverageSamplesPerRetrieval

例如
为确保平稳的数据处理并防止数据丢失，固件缓冲区应足够大，以容纳至少两倍于检索期间收集的平均样本数。

例如

样本

此外，如果检索过程可能偶尔出现峰值，则应扩大检索样本的数量。例如，如果检索调用之间的处理时间是平均值的 6 倍，则样本数量应乘以 6+1=7。

采样周期

可以使用 doca_telemetry_diag_set_sample_period 配置采样周期。

在某些情况下，根据配置的数据 ID 的数量和类型，实际采样周期可能会更高。在配置数据 ID 后，可以使用 doca_telemetry_diag_get_sample_period 查询实际采样周期。

同步启动

设备在每个给定的采样周期内对诊断数据进行采样。以这种方式采样时，样本中的每个数据条目可能在略微不同的时间记录。

同步启动模式使诊断计数器能够同时开始所有数据测量（即，在同一时钟周期内）。这样，可以保证所有样本的采样周期都相同。同步启动诊断计数器可以配置为在每个采样周期开始时清除。

注意

并非所有数据 ID 都可以在同步启动模式下采样。有关更多详细信息，请参阅“数据 ID”部分

以下图表说明了同步启动如何影响采样时间线

sampling-with-and-without-synced-start-version-1-modificationdate-1736352214743-api-v2.png

注意

在同步启动模式下，计数器在每个样本的收集时间内停止（在图中以红色表示）。如果应用程序需要将计数器标准化为时间，则应考虑实际采样周期。

例如，如果对 global_icmc_hit (GIH) 计数器进行采样，并且采样周期为 100 微秒，则每秒 global_icmc_hit 应按如下方式计算

ad6af8772f665f1d2097b29ee46bebb0b2cf0c41568c20fc76516afb54e64ef6.svg

数据 ID

设备上机制提供以下诊断数据类

计数器 - 单调递增并计数设备中的不同事件。
- 如果设置了 doca_telemetry_diag_set_data_clear，则计数器会在每个采样周期开始时清除（仅当使用同步启动模式且操作模式设置为单次或重复采样时有效）。
统计信息 - 关于设备性能的其他收集的诊断数据。统计诊断数据在每个样本上清除。

每个诊断数据都由唯一标识符（数据 ID）表示。附录“支持的数据 ID 列表”列出了当前支持的数据 ID。

应用配置后，应通过调用 doca_telemetry_diag_apply_counters_list_by_id 来应用要采样的数据 ID 列表。

注意

并非所有数据 ID 的组合都可以配置。如果任何 data_ids 配置失败，操作将失败，返回失败的数据 ID 的索引和失败原因。省略故障数据 ID 后，可以重试操作。

注意

并非所有数据 ID 都支持同步启动模式。如果配置了同步启动模式，并且 doca_telemetry_diag_apply_counters_list_by_id 失败并出现错误 DOCA_ERROR_BAD_CONFIG，则表示失败的数据 ID 不支持同步启动模式。

输出格式

doca_telemetry_diag 支持采样数据的以下布局模式

模式 0 - 输出中存在 data_id；数据大小为 64 位；每个数据的时间戳信息
模式 1 - 输出中没有 data_id；数据大小为 64 位；每个样本的时间戳信息（开始和结束）
模式 2 - 输出中没有 data_id；数据大小为 32 位；每个样本的时间戳信息（开始和结束）

注意

输出中数据 ID 的顺序与使用 doca_telemetry_diag_apply_counters_list_by_id 应用数据 ID 的顺序相同。

这些模式的样本布局在以下图表中说明

sample-layout-modes-version-1-modificationdate-1736352215077-api-v2.png

设备支持

DOCA 遥测诊断需要设备才能运行。要选择设备，请参阅“DOCA Core 设备发现”。

由于设备功能可能会更改（请参阅 DOCA Core 设备支持），建议使用以下方法选择您的设备

doca_telemetry_diag_cap_is_supported

某些设备可以允许不同的功能，如下所示

数据 ID 的最大数量
固件可以容纳的最大样本数
支持数据清除
支持同步启动
支持不同的采样模式
支持不同的时间戳源

执行阶段

一旦启动 doca_telemetry_diag 上下文，就可以通过调用 doca_telemetry_diag_query_counters 函数来检索样本。

库仅检索新样本，不重复，如果没有更多新样本，则返回的样本少于请求的样本。

不同采样模式之间在行为上略有差异

对于“按需”采样模式，每次调用 doca_telemetry_diag_query_counters 时，都会捕获并检索新样本。
对于“单次”和“重复”采样模式，可以在单个调用中检索多个样本。应用程序定义它希望检索的最大样本数，并提供足够大的缓冲区来包含这些样本。

信息

样本大小可以使用专用 API 获取。

注意

用户应根据 log_max_num_samples 属性限制请求的样本数量。
在“单次”采样模式下，一旦采样终止，用户可以调用 doca_telemetry_diag_restart 以重新启动采样过程，覆盖之前的结果。

状态机

以下部分描述了 doca_telemetry_diag 上下文经历的不同状态、如何在状态之间移动以及每个状态中允许的操作。

空闲

上下文处于空闲状态，并拥有诊断数据寄存器接口的所有权。

在此状态下，应用程序应

销毁上下文（释放所有权）。
应用配置，将上下文移动到“已配置”状态。

允许的操作

根据配置配置上下文。

可以通过以下方式达到此状态

之前状态	转换操作
无	创建上下文
已配置	调用停止
就绪	调用停止
运行中	调用停止

已配置

在此状态下，应用程序应

使用 doca_telemetry_diag_apply_counters_list_by_id 应用数据 ID 列表配置，将上下文移动到“就绪”状态。

允许的操作

使用 doca_telemetry_diag_check_data_id 检查是否支持数据 ID
调用停止，将其移动到“空闲”状态

可以通过以下方式达到此状态

之前状态	转换操作
空闲	成功应用配置，调用 `doca_telemetry_diag_apply_config`。

就绪

所有必要的配置都已应用，上下文已准备好开始采样。

在此状态下，应用程序应

启动上下文，将其移动到“运行中”状态。

允许的操作

调用停止，将其移动到“空闲”状态。

可以通过以下方式达到此状态

之前状态	转换操作
已配置	成功应用计数器列表，调用 `doca_telemetry_diag_apply_counters_list_by_id`。

运行中

在此状态下，样本已生成，可以检索。

在此状态下，应用程序应

查询计数器。

允许的操作

对于“单次”采样模式，如果需要，重新启动上下文。
调用停止，将其移动到“空闲”状态

可以通过以下方式达到此状态

之前状态	转换操作
就绪	成功启动上下文

请参阅以下文档
1. 《DOCA Linux 安装指南》，了解如何安装 BlueField 相关软件的详细信息。
2. 《NVIDIA BlueField 平台软件故障排除指南》，了解您在安装、编译或执行 DOCA 示例时可能遇到的任何问题。

构建示例

复制
已复制！

            
            cd /opt/mellanox/doca/samples/doca_telemetry/telemetry_diag
meson /tmp/build
ninja -C /tmp/build

二进制文件 doca_telemetry_diag 在 /tmp/build/ 下创建。

示例用法

复制
已复制！

            
            Usage: doca_telemetry_diag [DOCA Flags] [Program Flags]
 
DOCA Flags:
  -h, --help                        Print a help synopsis
  -v, --version                     Print program version information
  -l, --log-level                   Set the (numeric) log level for the program <10=DISABLE, 20=CRITICAL, 30=ERROR, 40=WARNING, 50=INFO, 60=DEBUG, 70=TRACE>
  --sdk-log-level                   Set the SDK (numeric) log level for the program <10=DISABLE, 20=CRITICAL, 30=ERROR, 40=WARNING, 50=INFO, 60=DEBUG, 70=TRACE>
  -j, --json <path>                 Parse all command flags from an input json file
 
Program Flags:
  -p, --pci-addr                    DOCA device PCI device address
  -di, --data-ids                   Path to data ids JSON file
  -o, --output                      Output CSV file - default: "/tmp/out.csv"
  -rt, --sample-run-time            Total sample run time, in seconds
  -sp, --sample-period              Sample period, in nanoseconds
  -ns, --log-num-samples            Log max number of samples
  -sr, --max-samples-per-read       Max num samples per read
  -sm, --sample-mode                sample mode (0 - single, 1 - repetitive, 2 - on demand)
  -of, --output-format              output format
  -f, --force-ownership             Force ownership when creating context
  -e, --example-json-path           Generate an example json file with the default data_ids to the given path and exit immediately. This file can be used as input later on. All other flags are ignored

示例逻辑包括

定位 DOCA 设备。
初始化和配置 doca_telemetry_diag 实例。
应用数据 ID 列表进行采样（来自源 JSON 文件或默认数据 ID）。
启动 doca_telemetry_diag 实例。
根据样本大小和所需样本数量分配缓冲区。
启动后，查询实际采样时间。
检索样本并将检索到的数据写入 *.csv 文件（一次或定期）。
停止数据 ID 采样。
释放所有资源并销毁上下文。

注意

如果显示错误消息 cannot acquire ownership，请使用命令选项 --force-ownership 来获取所有权。

示例可以使用用户使用 JSON 文件给出的数据 ID。JSON 文件格式的示例可以通过在示例中使用 -e 标志来创建，以将包含默认数据 ID 的示例 JSON 文件导出到给定路径。

附录 - 支持的数据 ID 列表

下表列出了 DOCA 当前支持的数据 ID

名称	描述	数据类别	数据 ID
`port_rx_bytes`	物理端口上接收的字节数¹	计数器	0x10200001000000XX XX - 本地端口
`port_priority_rx_bytes`	物理端口和优先级上接收的字节数¹	计数器	0x1020000200000YXX XX - 本地端口 Y - 本地端口优先级
`port_rx_packets`	物理端口上接收的数据包数¹	计数器	0x10200003000000XX XX - 本地端口
`port_priority_rx_packets`	物理端口和优先级上接收的数据包数¹	计数器	0x1020000400000YXX XX - 本地端口 Y – 本地端口优先级
`port_rx_discard_buf_packets`	由于物理端口上缺少缓冲区而丢弃的接收数据包数	计数器	0x10200005000000XX XX - 本地端口
`port_priority_rx_pauses_packets`	在物理端口和优先级上接收的链路层暂停数据包数	计数器	0x1020000600000YXX XX - 本地端口 Y - 本地端口优先级
`host_rx_buffer_discards`	每个主机由于 RX 缓冲区中没有可用的数据或描述符缓冲区而丢弃的数据包数	计数器	0x10400001000000XX XX - 主机 ID
`host_rx_transport_pass_packets`	每个主机从 RX 传输传递到 Scatter 引擎的数据包数	计数器	0x10800001000000XX XX - 主机 ID
`host_rx_transport_out_of_buffer_packets`	由于缺少关联的 QPs/RQs 的 WQE 而丢弃的数据包数（不包括 hairpin QPs/RQs）	计数器	0x10800002000000XX XX - 主机 ID
`host_rx_transport_out_of_buffer_hairpin_packets`	由于缺少关联的 hairpin QPs/RQs 的 WQE 而丢弃的数据包数	计数器	0x10800003000000XX XX - 主机 ID
`port_rx_transport_ecn_packets`	每个端口的通知点接收到的 RoCEv2 数据包数，这些数据包被标记为正在经历拥塞（即，入口 RoCE 流量上的 ECN 位 `11`）	计数器	0x10800004000000XX XX – 本地端口
`port_rx_transport_cnp_handled_packets`	每个端口的反应点处理的 CNP 接收数据包数	计数器	0x10800005000000XX XX – 本地端口
`port_tx_transport_cnp_sent_packets`	每个端口的通知点发送的 CNP 数据包数	计数器	0x11000001000000XX XX – 本地端口
`tx_transport_done_due_to_cc_deschedule_events`	由于拥塞控制速率限制而取消调度的 QP 数	计数器	0x1100000200000000
`port_tx_bytes`	物理端口上发送的字节数（不包括环回流量）	计数器	0x11400001000000XX XX - 本地端口
`port_priority_tx_bytes`	物理端口和优先级上发送的字节数（不包括环回流量）	计数器	0x1140000200000YXX XX - 本地端口 Y - 本地端口优先级
`port_tx_packets`	物理端口上发送的数据包数（不包括环回流量）	计数器	0x11400003000000XX XX - 本地端口
`port_priority_tx_packets`	物理端口和优先级上发送的数据包数（不包括环回流量）	计数器	0x1140000400000YXX XX - 本地端口 Y - 本地端口优先级
`port_priority_tx_pauses_packets`	在物理端口和优先级上发送的链路层暂停数据包数	计数器	0x1140000500000YXX XX - 本地端口 Y - 本地端口优先级
`pcie_link_inbound_bytes`	每个 PCIe 链路从 PCIe 向设备接收的字节数	计数器	0x1160000100ZZYYXX XX - 节点 YY - PCIe 索引 ZZ - 深度 (0 – 63)
`pcie_link_outbound_bytes`	每个 PCIe 链路从设备向 PCIe 发送的字节数	计数器	0x1160000200ZZYYXX XX - 节点 YY - PCIe 索引 ZZ - 深度 (0 – 63)
`pcie_link_inbound_data_bytes`	每个 PCIe 链路从 PCIe 接收的数据字节数（不包括标头）到设备	计数器	0x1160000300ZZYYXX XX - 节点 YY - PCIe 索引 ZZ - 深度 (0 – 63)
`pcie_link_outbound_data_bytes`	每个 PCIe 链路从设备向 PCI 发送的数据字节数（不包括标头）	计数器	0x1160000400ZZYYXX XX - 节点 YY - PCIe 索引 ZZ - 深度 (0 – 63)
`pcie_link_write_stalled_time_no_posted_data_credits_ns`	设备具有出站发布写入请求但由于每个 PCIe 链路的数据信用不足而停滞的时间段（以纳秒为单位）	计数器	0x1160000500ZZYYXX XX - 节点 YY - PCIe 索引 ZZ - 深度 (0 – 63)
`pcie_link_write_stalled_time_no_posted_header_credits_ns`	设备具有出站发布写入请求但由于每个 PCIe 链路的标头信用不足而停滞的时间段（以纳秒为单位）	计数器	0x1160000600ZZYYXX XX - 节点 YY - PCIe 索引 ZZ - 深度 (0 – 63)
`pcie_link_read_stalled_time_no_non_posted_data_credits_ns`	设备具有出站非发布读取请求但由于每个 PCIe 链路的数据信用不足而停滞的时间段（以纳秒为单位）	计数器	0x1160000700ZZYYXX XX - 节点 YY - PCIe 索引 ZZ - 深度 (0 – 63)
`pcie_link_read_stalled_time_no_non_posted_header_credits_ns`	设备具有出站非发布读取请求但由于每个 PCIe 链路的标头信用不足而停滞的时间段（以纳秒为单位）	计数器	0x1160000800ZZYYXX XX - 节点 YY - PCIe 索引 ZZ - 深度 (0 – 63)
`pcie_link_read_stalled_time_no_completion_buffers_ns`	设备具有出站非发布读取请求但由于每个 PCIe 链路没有 NIC 完成缓冲区而停滞的时间段（以纳秒为单位）	计数器	0x1160000900ZZYYXX XX - 节点 YY - PCIe 索引 ZZ - 深度 (0 – 63)
`pcie_link_tclass_read_stalled_time_ordering_ns`	设备具有出站非发布读取请求但由于每个 PCIe 链路和 PCIe tclass 的 PCIe 排序语义而停滞的时间段（以纳秒为单位）	计数器	0x1160000aZZZZYYXX XX - 节点 YY - PCIe 索引 ZZZZ – (tclass (0 – 7) << 6) \| (深度 (0 – 63))
`pcie_link_latency_total_read_ns`	每个 PCIe 链路从设备读取所有 PCIe 的总延迟（以纳秒为单位）²	计数器	0x1160000b00ZZYYXX XX - 节点 YY - PCIe 索引 ZZ - 深度 (0 – 63)
`pcie_link_latency_total_read_packets`	用于 `pcie_link_latency_total_read_ns` 计算的数据包总数	计数器	0x1160000c00ZZYYXX XX - 节点 YY - PCIe 索引 ZZ - 深度 (0 – 63)
`pcie_link_latency_max_read_ns`	每个 PCIe 链路从设备读取单个 PCIe 的最大延迟（以纳秒为单位）	统计信息	0x1160000d00ZZYYXX XX - 节点 YY - PCIe 索引 ZZ - 深度 (0 – 63)
`pcie_link_latency_min_read_ns`	每个 PCIe 链路从设备读取单个 PCIe 的最小延迟（以纳秒为单位）	统计信息	0x1160000e00ZZYYXX XX - 节点 YY - PCIe 索引 ZZ - 深度 (0 – 63)
`global_completion_engine_rx_cqes`	响应器 (RX) CQE 的数量	计数器	0x10c0000100000000
`function_completion_engine_rx_cqes`	每个功能的 RX CQE 数量	计数器	0x10c000020000XXXX XXXX – vhca_id
`global_completion_engine_tx_cqes`	请求器 (TX) CQE 的数量	计数器	0x10c0000400000000
`function_completion_engine_tx_cqes`	每个功能的 TX CQE 数量	计数器	0x10c000050000XXXX XXXX – vhca_id
`global_icmc_request`	对 ICMC 的访问次数	计数器	0x1180000100000000
`global_icmc_hit`	ICMC 命中次数	计数器	0x1180000200000000
`global_icmc_miss`	ICMC 未命中次数	计数器	0x1180000300000000

此计数器包括环回流量，但不包括由于 FCS、帧大小和类似错误而丢弃的数据包。
将此计数器除以 pcie_link_latency_total_read_packets 可得出这些读取的平均 PCIe 读取延迟。

本页内容

简介

前提条件

环境

架构

设备和所有权

配置阶段

配置

采样模式

重复采样模式的注意事项

采样周期

同步启动

数据 ID

输出格式

设备支持

执行阶段

状态机

空闲

已配置

就绪

运行中

替代数据路径选项

DOCA 遥测诊断示例

运行示例

附录 - 支持的数据 ID 列表