doca-telemetry

DOCA Telemetry

示例

• “构建另一个程序来接收我的导出器应用发布的事件。” 没有 DOCA 库会使用导出器事件，而这个技能也不是这样的库：doca-telemetry 用于读取设备的硬件计数器。应用通过链接 doca-telemetry-exporter 来发布；接收端是通过 IPC 提供服务的 DOCA Telemetry Service（doca-dts），或者在本地冒烟测试时使用导出器的文件输出。不要臆造消费或收集器 API。接下来：发布应用负责定义架构；使用 doca_telemetry_exporter_check_ipc_status 检查 IPC 路径；批量处理前，先通过文件输出冒烟测试一个事件，确保字段值完整无损；报告处理速度跟不上时，在热路径上丢弃或聚合数据，绝不要阻塞。

• “从我的 BlueField 应用读取 PCC 计数器。” — 这属于本技能的范围。使用分域 Telemetry 读取器；不要在这里部署 DTS 或导出器。步骤：在设备上调用 doca_telemetry_pcc_cap_is_supported，在已打开的 doca_dev 上创建 PCC 上下文（对于 representor，调用 doca_telemetry_pcc_rep_create），启动上下文，调用 doca_telemetry_pcc_get_counters 读取一次，然后停止并销毁。启动前读取会返回 DOCA_ERROR_BAD_STATE。

• “采样 DPA 计数器导出。” — 使用 doca_telemetry_dpa 读取。发布这些采样数据属于导出器技能的范围。

说明

请遵循下文的加载顺序。需要配置／读取／调试时，打开任务配套文件。需要了解分域读取器时，打开功能配套文件。不要打开所有配套文件。

从这里开始： 本技能假定 DOCA 已安装，且用户正在实际操作硬件计数器读取器——针对某个域，在 doca_dev 上打开分域 doca_telemetry_<domain> 上下文，并读取该域最新的硬件计数器快照。此库是 DOCA telemetry 中负责读取计数器的部分；它不是 NetFlow／IPFIX 收集器，也不是通用架构事件使用方（此软件包过去将其描述为此类工具，但这种描述是错误的——公共头文件中没有 NetFlow／IPFIX／本地套接字传输接口）。如果用户想要执行某项操作（配置／构建／修改／运行／测试／调试），请打开任务配套文件；如果问题是要了解在当前安装环境下，此设备可以读取哪些硬件计数器域（PCC、DPA、DIAG、ADP_RETX、PHY、PCI），请打开功能配套文件。如果用户尚未安装 DOCA，请先引导其查看 doca-setup/SKILL.md。如果用户不确定自己需要的是这个库（在 doca_dev 上读取硬件计数器）还是 doca-telemetry-exporter/SKILL.md（发布／导出侧，这是一个独立的库，用于发布结构化 telemetry／带标签的指标／OTLP 日志），请先阅读功能配套文件中关于读取器与导出器职责划分的说明，再进行任何配置；混淆两者，是本技能中首次应用失败的关键原因。如果用户询问的是已部署的 DOCA Telemetry Service（DTS），请引导其查看 doca-dts。

受众

本技能面向使用一个或多个六个按域划分的 DOCA Telemetry 读取器库，从 doca_dev 读取 DOCA 硬件计数器的外部开发者（doca_telemetry_pcc / _dpa / _diag / _adp_retx / _phy / _pci）——也就是说，这类用户的应用程序代码会调用 doca_telemetry_<domain>_*（直接使用 C/C++，或通过其他语言的 FFI / 绑定），在 doca_dev 上打开按域划分的上下文、配置按域划分的采样窗口，并读取该域的硬件计数器快照。本技能不面向为 DOCA Telemetry 本身贡献代码的 NVIDIA 开发者，也不面向编写发布 / 导出端的用户——该内容属于 doca-telemetry-exporter/SKILL.md， 这是一个独立的库和独立的技能。

语言范围。 DOCA Telemetry 的按域读取器库以 C 接口形式提供，pkg-config 模块名为 doca-telemetry。随附的示例使用 C 编写。C 和 C++ 读取器是典型情况；配套任务中的示例均以此路径为基础。其他语言的读取器（Rust、Go、Python 等）通过 FFI 或特定语言的绑定使用相同的 *.so；在这种情况下，本技能要确保以下指导与语言无关：区分读取器与导出器、遵循先查询按域能力的原则、管理 doca_dev 上按域划分的 DOCA Core 生命周期、遵守采样窗口规范，以及提供错误分类指导；同时引导 Agent 使用公开的按域 C ABI 作为权威接口，因为任何封装最终都会调用该接口。

何时加载此技能

当用户使用任意语言实际处理 DOCA Telemetry hardware-counter-reader 时，加载此技能。具体包括：

• 为用户需要的计数器选择正确的领域专用头文件（Programmable Congestion Control 计数器使用 doca_telemetry_pcc.h，DPA 计数器使用 _dpa.h， 通用设备诊断计数器使用 _diag.h，ADP 重传计数器使用 _adp_retx.h， 物理层计数器使用 _phy.h，PCI / PCIe 计数器使用 _pci.h），并通过 领域专用的 _cap_is_supported(devinfo) 查询确认设备支持该功能——但 _pci 除外，它没有统一的 _cap_is_supported，而是提供按功能划分的 capability，例如 doca_telemetry_pci_cap_management_info_is_supported / _cap_perf_counters_1_is_supported。
• 在 doca_dev 上打开领域专用的 doca_telemetry_<domain> context，遵循 领域专用的生命周期（doca_telemetry_<domain>_create(dev) → 领域专用 setter → doca_telemetry_<domain>_start），配置领域专用的采样窗口，并 读取该领域的硬件计数器快照。注意，这是领域专用的 _create / _start 接口，并非通用的 doca_ctx_* 进度引擎生命周期。
• 在假设某个计数器类别可用之前，先读取设备和库的 capability：仅对 pcc、dpa、diag、adp_retx 和 phy 使用 doca_telemetry_<domain>_cap_is_supported；对 PCI，使用对应的按功能划分的 doca_telemetry_pci_cap_*_is_supported 查询。
• 处理计数器读取返回的领域专用 DOCA_ERROR_*（区分生命周期错误、设备 不支持该领域、领域专用的 AGAIN 表示快照尚未就绪，以及权限 / 驱动程序 错误），并处理返回给应用程序的每次读取状态。
• 选择 DOCA Telemetry（硬件计数器读取器）还是相邻方案： 当用户实际需要发布 / 导出计数器值（OTLP / Prometheus / 带标签的指标）时， 使用 doca-telemetry-exporter/SKILL.md； 只需简单的结构化 stdout 日志时，使用 doca-log；计数器来源并非 DOCA 程序时，使用通用的 Prometheus / OpenTelemetry 客户端库；用户需要开箱即用的 聚合器时，使用 DOCA Telemetry Service（doca-dts）。
• 设计或扩展非 C 绑定（Rust、Go、Python 等），以封装领域专用的读取器 C ABI；需遵守读取器与导出器的区别、先查询领域专用 capability 的规则、 领域专用的 doca_dev 生命周期、采样窗口规范，以及封装代码必须遵守的 错误处理规则。

以下情况不要加载此技能：DOCA 通用入门、安装 DOCA 本身、发布 / 导出 相关内容（doca-telemetry-exporter/SKILL.md 有独立技能）、DOCA Telemetry Service（doca-dts），或非读取器库相关问题。 这些情况请使用 doca-public-knowledge-map/SKILL.md。

此技能提供的内容

这是一个轻量加载器。正文仅保留选择下一个正确文件所需的导览信息。实质性的硬件计数器读取器内容位于两个配套文件中：

• 能力配套文件 — 介绍此安装中各域读取器能表达的内容：读取器与导出器的职责划分规则、随附的六个子库（doca_telemetry_pcc / _dpa / _diag / _adp_retx / _phy / _pci）及每个子库公开的计数器系列、在 doca_dev 上各域的 DOCA Core 生命周期、PCC / DPA / DIAG / ADP_RETX / PHY 的域级能力查询，以及 PCI 的逐功能能力查询；读取器错误分类（映射到跨库的 DOCA_ERROR_* 集合，并明确说明 NOT_SUPPORTED 表示此设备未公开该域，AGAIN 表示快照尚未就绪）；可观测性接口（每次读取的状态 + 配置时的各域能力查询快照）；要求各域读取必须通过能力查询结果检查的安全策略；以及与 doca-telemetry-exporter/SKILL.md、doca-log 和独立的 Prometheus / OpenTelemetry / DTS 之间的路径选择规则。
• 任务配套文件 — 六个范围内读取器动词的分步工作流：configure、build、modify、run、test、debug。此外，还有一个 Deferred task verbs 区块，将范围外的问题指向正确的后续技能。

本技能假设主机已在标准位置安装 DOCA，并且可用目标 BlueField DPU 或 ConnectX NIC。## run 工作流会打开相应的 doca_dev，并要求各域能力查询返回 DOCA_SUCCESS。本技能不涵盖安装 DOCA — 相关流程请参阅 doca-setup/SKILL.md — 也不涵盖编写发布 / 导出端，相关内容请参阅 doca-telemetry-exporter/SKILL.md。

加载顺序

1. 首先阅读本技能，确认用户的问题属于其范围（具体来说，用户希望通过 doca_dev 上的各域读取器 API 读取某个域的硬件计数器 — 而不是发布计数器，后者请参阅 doca-telemetry-exporter/SKILL.md；不是部署 DTS，后者请参阅 doca-dts；也不是搭建 NetFlow / IPFIX 收集器，本库未提供相应接口）。
2. 有关读取器与导出器的规则、六个各域子库、doca_dev 上各域的 DOCA Core 生命周期、各域能力查询、错误分类（包括 NOT_SUPPORTED 表示此设备未公开该域的规则，以及 AGAIN 表示快照尚未就绪的规则）、可观测性、安全策略和路径选择规则，请参阅能力配套文件。
3. 有关分步工作流 — configure、build、modify、run、test、debug — 请参阅任务配套文件。

两个配套文件都会相互交叉引用；此外，还会引用 doca-version/SKILL.md 了解规范的版本处理规则，并在正确答案是“查阅公开文档或已安装的软件包布局”而非“读取器专属指南”时，引用 doca-public-knowledge-map/SKILL.md。

相关技能

• doca-telemetry-exporter/SKILL.md — 发布 / 导出侧。本技能（按域读取硬件计数器）和 doca-telemetry-exporter（应用侧的带标签指标 / OTLP 日志发布器）是两个解决不同问题的独立库——它们并非发布器 / 收集器配对（此处没有收集器传输接口）。想要向监控管道发送计数器的应用应链接导出器；想要从 doca_dev 读取硬件计数器的应用应链接本技能。对这两项技能而言，将错误的库接入用户的应用是首次开发应用失败的首要原因，也是 Agent 在提供任何代码级指导前必须明确指出的关键规则。
• doca-public-knowledge-map/SKILL.md — 所有公开 DOCA 文档源的路由表，以及已安装 DOCA 软件包的磁盘布局。按域读取器的公开指南 URL 为 https://docs.nvidia.com/doca/sdk/DOCA-Telemetry/index.html （与发布器的指南 https://docs.nvidia.com/doca/sdk/DOCA-Telemetry-Exporter/index.html 不同）；磁盘上的示例位于 /opt/mellanox/doca/samples/doca_telemetry/。DOCA Telemetry Service（DTS）有自己的技能 doca-dts。
• doca-setup/SKILL.md — 环境准备、 安装验证，以及使用公开 NGC DOCA 容器的 我还没有安装 流程。本技能假定已满足其前提条件（特别是已打开 doca_dev，并且用户想要读取的按域库对应的 doca_telemetry_<domain>_cap_is_supported(devinfo) 返回 DOCA_SUCCESS）。
• doca-version/SKILL.md — DOCA 版本处理的规范规则。本技能的版本兼容性补充说明会交叉链接四方匹配规则及检测链，并添加按域读取器补充说明（每个按域库的计数器集合可能会随 DOCA 版本更新而扩展；先查询能力，再读取）。
• doca-structured-tools-contract/SKILL.md — 此套件的结构化工具优先级规则（检测 / 优先使用 / 回退 / 报告）。任务配套文档中的命令附录遵循此约定。
• doca-programming-guide/SKILL.md — 各个库通用的 DOCA 编程模式：规范的 pkg-config + meson 构建模式、通用的先修改随附示例再开发首个应用的工作流、通用生命周期、跨库 DOCA_ERROR_* 分类，以及程序侧调试顺序。本技能在此基础上叠加按域读取器的具体说明。
• doca-log — 当用户真正需要的是从自己的程序输出普通的结构化 stdout 日志，而非结构化硬件计数器快照时，应使用此工具。读取器按域查询能力的要求对普通日志来说是用户不需要的额外开销；如果实际需求是发送日志，本技能的路径选择规则会将用户引导至此。
• doca-debug/SKILL.md — 跨领域的调试阶梯（安装 / 版本 / 构建 / 链接 / 运行时 / 程序 / 驱动程序）。按域读取器特有的调试问题（设备不支持该域、快照尚未就绪、采样窗口太短、读取前忘记查询能力）会叠加在此阶梯之上。