| 开源协议 | Apache-2.0 |
| 名称 | doca-telemetry |
| 描述 | > 使用此技能从 doca_dev 通过每个域的遥测读取器库（doca_telemetry_pcc、_dpa、_diag、_adp_retx、_phy 和 _pci）读取 DOCA 硬件计数器事件。涵盖能力检查、上下文创建、启动以及每个域的读取或采样。隐式请求的触发词，例如“从我的 BlueField 应用读取 PCC 计数器”、“采样 DPA 计数器导出”或“从此 doca_dev 暴露 PHY、PCI 或 DIAG 计数器”。这是计数器读取器表面，而不是 NetFlow、IPFIX 或本地套接字收集器。将发布和导出路由到 doca-telemetry-exporter；将已部署的 DOCA Telemetry Service (DTS)、收集器以及普通 stdout 日志记录路由到别处。 metadata: kind: library compatibility: > 需要 DOCA SDK 安装在 Linux（Ubuntu 22.04/24.04 或 RHEL/SLES）上的 /opt/mellanox/doca，并连接 BlueField DPU 或 ConnectX NIC。通过 pkg-config doca-telemetry 读取用户的本地安装，并检查 /opt/mellanox/doca/{lib,include,samples,applications}。 |
DOCA 遥测
从这里开始： 此技能假定 DOCA 已安装，用户正在进行 动手硬件计数器读取器工作 —— 在 doca_dev 上打开一个特定于域的 doca_telemetry_<domain> 上下文，并读取该域的最新硬件计数器快照。该库是 DOCA 遥测的计数器-读取器一半；它不是 NetFlow/IPFIX 收集器，也不是通用 schema 事件消费者（该 bundle 之前以这种方式描述是错误的 —— 公共头中没有 NetFlow/IPFIX/本地套接字传输面）。如果用户想 做 某事（配置 / 构建 / 修改 / 运行 / 测试 / 调试），打开 TASKS.md；当问题是 这个设备在此安装上可以读取哪些硬件计数器域（PCC、DPA、DIAG、ADP_RETX、PHY、PCI）时，打开 CAPABILITIES.md。如果用户尚未安装 DOCA，请先路由到 doca-setup。如果用户不清楚是要这个库（在 doca_dev 上的硬件计数器读取器）还是 doca-telemetry-exporter（发布/导出一侧，是一个单独的库，发布结构化遥测 / 标签指标 / OTLP 日志），在配置任何内容之前请阅读 CAPABILITIES.md ## 能力和模式 中的读取器与导出者角色划分；将两者混用是该技能首要的首次应用失败。如果用户问的是 已部署的 DOCA Telemetry Service (DTS)，请路由到 doca-public-knowledge-map 非目标 —— DTS 不在本 bundle 的范围内。
受众
此技能服务于 外部开发人员，他们构建 从 doca_dev 通过六个特定于域的 DOCA Telemetry 读取器库之一或多个 （doca_telemetry_pcc / _dpa / _diag / _adp_retx / _phy / _pci）读取 DOCA 硬件计数器的应用程序 —— 即，用户的应用程序代码调用 doca_telemetry_<domain>_*（直接用 C/C++，或通过 FFI / 绑定从其他语言）来在 doca_dev 上打开特定于域的上下文，配置该域的采样窗口，并读取该域的硬件计数器快照。它 不是 给那些为 DOCA Telemetry 本身贡献的 NVIDIA 开发人员，也 不是 给那些编写 发布 / 导出 侧的用户 —— 那属于 doca-telemetry-exporter，这是一个单独的库和单独的技能。
语言范围。 DOCA Telemetry 的每个域读取器库以 C 接口交付，pkg-config 模块名称为 doca-telemetry。随附的示例用 C 编写。C 和 C++ 读取器是典型用例；TASKS.md 中的实例假设该路径。其他语言读取器（Rust、Go、Python 等）通过 FFI 或特定语言绑定使用相同的 *.so；在这种情况下，该技能的贡献是使读取器与导出者的区分、每个域的能力先查询纪律、在 doca_dev 上的每个域的 DOCA Core 生命周期、采样窗口纪律以及错误分类指南保持语言无关，并将代理路由到公共每个域 C ABI 作为最终权威接口。
何时加载此技能
当用户在做 DOCA Telemetry 硬件计数器读取器工作（任何语言）时加载此技能。具体来说：
- 为用户想要的计数器选择正确的每域头文件（
doca_telemetry_pcc.h用于可编程拥塞控制计数器，_dpa.h用于 DPA 计数器，_diag.h用于通用设备诊断计数器，_adp_retx.h用于 ADP 重传计数器，_phy.h用于物理层计数器，_pci.h用于 PCI/PCIe 计数器），并通过每域_cap_is_supported(devinfo)查询确认设备支持 —— 除了_pci，它没有单个_cap_is_supported，而是公开每特性能力，如doca_telemetry_pci_cap_management_info_is_supported/_cap_perf_counters_1_is_supported。 - 在
doca_dev上打开每域doca_telemetry_<domain>上下文，遍历每域生命周期（doca_telemetry_<domain>_create(dev)→ 每域设置器 →doca_telemetry_<domain>_start），配置每域采样窗口，并读取该域硬件计数器快照。注意这是每域_create/_start表面，不是通用的doca_ctx_*进度引擎生命周期。 - 在假设某个计数器族可用之前，先读取设备 + 库能力表面：仅对
pcc、dpa、diag、adp_retx和phy使用doca_telemetry_<domain>_cap_is_supported；PCI 使用匹配的每特性doca_telemetry_pci_cap_*_is_supported查询。 - 处理计数器读取返回的每域
DOCA_ERROR_*（生命周期 vs. 设备不支持此域 vs. 每域AGAIN表示快照未就绪 vs. 权限/驱动），以及向应用程序报告的每次读取状态。 - 在 DOCA Telemetry（硬件计数器读取器）和相邻选项之间选择：当用户实际想要发布/导出计数器值（OTLP / Prometheus / 标签指标）时，使用
doca-telemetry-exporter；当普通结构化 stdout 日志足够时，使用doca-log；当计数器源是非 DOCA 程序时，使用通用 Prometheus / OpenTelemetry 客户端库；当用户想要交钥匙聚合器时，使用外部产品化的 DOCA Telemetry Service（DTS，超出范围）。 - 设计或扩展非 C 绑定（Rust、Go、Python…）封装每域读取器 C ABI —— 以满足读取器与导出者区分、每域能力先查询规则、每域
doca_dev生命周期、采样窗口纪律以及包装器必须遵循的错误规则。
不要 将此技能用于一般 DOCA 定向、DOCA 本身的安装、发布/导出侧（doca-telemetry-exporter有自己的技能）、外部产品化的 DOCA Telemetry Service（DTS —— 超出范围）或非读取器库问题。对于这些，请使用 doca-public-knowledge-map。
此技能提供什么
这是一个薄加载器。主体只保留选择正确下一个文件所需的定向。实质性的硬件计数器读取器材料在两个附随文件中：
CAPABILITIES.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、doca-log和独立 Prometheus / OpenTelemetry / DTS 的路径选择规则。TASKS.md—— 六个范围内读取器动词的分步工作流：configure、build、modify、run、test、debug。还有一个“延迟任务动词”块，将范围外的问题指向正确的下一个技能。
该技能假设主机已安装 DOCA（标准位置），并且有可用的目标 BlueField DPU 或 ConnectX NIC。TASKS.md ## run 工作流打开相应的 doca_dev，并要求每域能力查询返回 DOCA_SUCCESS。它不涵盖安装 DOCA —— 该路径经 doca-setup —— 也不涵盖编写发布/导出一侧，这属于 doca-telemetry-exporter。
加载顺序
- 首先阅读此
SKILL.md以确认用户的问题在范围内（特别是，用户想要通过每域读取器 API 在doca_dev上读取每域硬件计数器 —— 而不是发布计数器，后者属于doca-telemetry-exporter；而不是部署 DTS，这超出范围；也不是构架 NetFlow/IPFIX 收集器，此库不公开此类接口的表面）。 - 对于读取器与导出者规则、六个每域子库、在
doca_dev上的每域 DOCA Core 生命周期、每域能力查询、错误分类法（包括NOT_SUPPORTED-表示-域-未在-此设备-上-公开的规则和AGAIN-表示-快照-未就绪的规则）、可观测性、安全策略和路径选择规则，请参阅 CAPABILITIES.md。 - 有关分步工作流 —— 配置、构建、修改、运行、测试、调试 —— 请参阅 TASKS.md。
两个附随文件互相交叉链接，与 doca-version 链接以获取规范的版本处理规则，与 doca-public-knowledge-map 链接，当正确答案是“在公共文档或已安装包布局中查找”而不是“读取器特定指导”时。