doca-telemetry-utils

DOCA Telemetry Utils

示例

• “这台 BlueField 实际暴露了哪些诊断计数器？”——这是本工具的适用范围。先枚举，再探测；不要在这里启动采集器应用。
• “我的导出器将计数器命名为 port_rx_bytes，但下游什么都看不到。”——将名称转换为 Data ID，并探测每台设备是否支持，再修改导出器。

快速排查：导出器已发布，但采集器什么也没收到

1. doca_telemetry_utils get-counters：此版本是否识别该计数器？
2. doca_telemetry_utils <counter>：打印其属性选项。
3. doca_telemetry_utils <counter> <properties>：解析 Data ID。
4. doca_telemetry_utils <device PCI> <counter> <properties>：如果此设备显示“不支持”，说明导出器会静默丢弃该计数器；不要提交该计数器。
5. doca_telemetry_utils <0x... Data ID>：反向解析在线路上捕获的 ID。
6. 使用 doca-version 检查主机和 BlueField 版本是否匹配。
7. 如果每一步都能顺利解析，请转交给 doca-telemetry 的 ## debug。

逐字引用工具的输出；切勿手动构造 Data ID。

说明

请遵循下方的加载顺序。打开任务配套文件，了解安装／运行／测试。打开功能配套文件，了解如何发现架构以及如何与遥测库配合使用。 不要打开所有配套文件。

从何处开始： 这是用于调用 doca_telemetry_utils 的工具技能——该命令行界面已记录在案，运行于主机端，可通过发现计数器架构、在计数器名称与 Data ID 之间进行转换，以及探测每台设备是否支持计数器，来支持 DOCA Telemetry 导出器／采集器流水线。打开任务配套文件，从 ## install 开始查看主机端先决条件，并从 ## run 开始查看已记录的三类调用方式（枚举／名称→ID／ID→名称）。如果问题涉及此工具实际能发现遥测架构中的哪些内容、它如何与开发侧的 doca-telemetry/SKILL.md 和导出器库配合使用、如何在提交导出器配置前确认设备支持某个计数器，或为什么导出器流水线会静默丢弃某个指标，请打开功能配套文件。

如何使用此技能。 阅读此文件，然后在配套文件中搜索问题所需的 ## <name> 标题，并阅读该完整章节。仅依据其中内容完整作答，并且仅引用其中的符号和命令。不要浏览文档；请使用 doca-public-knowledge-map 中的入口点。将环境检查作为命令提供给用户的 DOCA 主机。对于超出范围的请求，指出负责该请求的技能，然后停止。

此技能是 DOCA Telemetry 部署的运维侧支持工具。它不是开发侧采集器库（即 doca-telemetry/SKILL.md），也不是开发侧发布器库（即 doca-telemetry-exporter——参见 doca-telemetry ## Related skills（doca-telemetry/SKILL.md#related-skills）），也不是 DOCA Telemetry Service (DTS) 部署指南（请转交给 doca-dts）。 这是三个独立的领域；将它们混为一谈，是遥测问题初次排查中最常见的错误。

此技能擅长回答的示例问题

此技能旨在回答 doca_telemetry_utils 问题的各个类别，每个类别都附有一个完整示例。类别是关键所在；完整示例只是其中一个实例。

• “我的 exporter 显示正在发送 port_rx_bytes，但下游什么都没收到——我哪里弄错了？” — 完整示例：“我的 exporter 配置中有一个计数器名称字符串，但 collector 没有收到任何名称匹配的事件”。由 capabilities 配套文档中的名称 ↔ Data ID 转换步骤，以及 tasks 配套文档中的设备支持探测来回答：exporter 发送的是 Data ID，而不是名称；如果配置中的名称解析出的 Data ID 不受设备支持，该项就会被静默丢弃。
• “这台 BlueField 实际公开了哪些 DOCA 诊断计数器？” — 完整示例：“在编写 exporter 配置之前，列出我的 BlueField-3 的完整计数器架构”。由 capabilities 配套文档中的架构发现调用类别来回答 （doca_telemetry_utils get-counters 会列出诊断数据接口已知的所有计数器名称；再结合逐设备探测以确认设备支持情况）。
• “我在捕获的日志中有一个 Data ID——它对应什么计数器？” — 完整示例：“下游使用者输出了 Data ID: 0x1160000600030201——请将其转换回计数器，以便我对照公开指南”。 由 capabilities 配套文档中的反向解析调用类别，以及 tasks 配套文档中的 ID 编码属性规则来回答（Data ID 包含计数器的属性维度；反向解析会报告这些维度）。
• “这个计数器有哪些属性维度？有效值是什么？” — 完整示例：“我知道计数器是 pcie_link_write_stalled_time_*——node / pcie_index / depth 分别是什么意思？设备接受哪些值？”。由 capabilities 配套文档中的属性维度表，以及不带参数调用 <name> 来回答；此调用会打印有文档说明的属性选项、单位和单位专属轴。
• “在将此计数器提交到 exporter 配置之前，如何确认设备支持它？” — 完整示例：“在编写 exporter 配置之前，验证 BlueField 是否在 PCIe 地址 X 上公开了 node=1 的 port_rx_bytes”。由 capabilities 配套文档中的逐设备支持探测（<device PCI> <name> [properties]），以及 tasks 配套文档中的提交前检查规则来回答。
• “我的安装中有 doca_telemetry_utils 吗？它是否与匹配版本的 doca-telemetry 库配套？” — 完整示例：“我的 exporter 目标所对应的诊断数据计数器集，是否适用于此 DOCA 版本？”。由 capabilities 配套文档中的版本叠加说明来回答；该说明会指向规范的 doca-version/SKILL.md 链，并补充工具 ↔ doca-telemetry 库 架构版本匹配规则。

何时加载此技能

当用户需要，或 Agent 需要在安装了 DOCA 的真实主机上调用 doca_telemetry_utils，并配合需要进行架构发现、逐设备支持验证或 Data ID 转换的导出器／收集器流水线时，加载此技能。 具体包括：

• 在编写新的 DOCA Telemetry 导出器配置前枚举完整的计数器架构（get-counters）。
• 在提交配置前，验证所选计数器和属性集能否解析为目标设备实际支持的 Data ID。
• 将从下游使用方捕获的 Data ID 反向解析为计数器名称和属性，以便与公开指南进行关联。
• 调查 “导出器已发送，但收集器未收到任何内容” 的报告（这是架构不匹配／不支持计数器的典型故障模式）。
• 在结构化的导出器配置基线中，生成 “此 BlueField + 此 DOCA 版本的已验证计数器集” 成果。
• 将导出器流水线迁移到其他 DOCA 版本，并确认先前支持的每个计数器在新版本上仍能正常解析。

一般 DOCA 概述、收集器／导出器库编程、DTS 部署或 DOCA 安装均不应加载此技能。对于这些需求，请转至 doca-public-knowledge-map/SKILL.md、doca-telemetry/SKILL.md 或 doca-setup/SKILL.md。

此技能提供的内容

这是一个轻量加载器。实质内容位于两个配套文件中：

• capabilities 配套文件——介绍 doca_telemetry_utils 可发现的内容，以及它如何与开发者侧接口配合：三类已记录的调用（枚举／名称→ID／ID→名称）、属性维度模型（计数器带有 node、pcie_index、depth 等属性轴，以及按单元划分的轴）、可选的逐设备能力探测（<device PCI> <name> 会针对设备运行已解析的计数器）、运维侧支持角色（这不是开发者侧库；它旨在确保导出器／收集器设置可靠）、版本对应关系（工具与 doca-telemetry 库架构版本配对）、分层错误分类（安装／解析／未知计数器／未知 Data ID／属性超出范围／设备不支持／版本／跨类别）、可观测性接口（仅标准输出），以及安全策略（此工具为只读；出错会导致下游指标静默丢失，而非程序崩溃）。
• tasks 配套文件——介绍适用任务动词的分步工作流：install（主机端 DOCA + Telemetry 组件的先决条件）、configure（轴的选择：调用类别、设备和计数器）、build（转至 install——该二进制文件随软件提供）、modify（拒绝——不要修改二进制文件；应修改调用方式，以及使用已解析 Data ID 的导出器／收集器配置）、run（三种已记录的调用）、test（让所选计数器依次经过名称 → Data ID → 逐设备探测 → 导出器配置 → 收集器接收，以验证全流程）、debug（逐项检查错误分类）、use（交接至开发者侧的 doca-telemetry 收集器／导出器流水线），以及 Deferred task verbs 区块。

此技能假设主机已安装 DOCA 和 Telemetry 组件；运维人员指定的 BlueField 对 DOCA 可见；并且使用已解析 Data ID 的导出器／收集器流水线正在编写，或已根据匹配的 doca-telemetry/SKILL.md 库版本完成编写。

本技能明确不包含的内容

本技能提供的是 Agent 指引，而非示例或脚本包。为明确划分范围，本技能特意不包含以下内容，也不应在拉取请求中添加：

• 逐字列出的计数器清单或数据 ID 表。 计数器集合会随 DOCA 版本和 BlueField 代际而变化；在本技能中固定清单会导致内容悄然过时。已安装二进制文件中的 doca_telemetry_utils get-counters 是权威来源。
• 预先制作的导出器 / 收集器配置。 配置因安装方式、设备和使用场景而异；本技能中打包的配置可能会误导采用不同设置的运维人员。
• DTS 部署方案。 DTS 是独立的 DOCA 服务，有自己的公开指南；请通过 doca-public-knowledge-map/SKILL.md 查找。
  本技能会解析 DTS 管道所需的计数器名称和 ID，但不会配置 DTS。
• 任何语言编写的包装器、解析器或脚本，用于处理该工具的输出。输出是简单的文本映射；如果用户想据此编写脚本，应阅读最新指南，并针对已安装的版本编写解析器。
• samples/ 或 reference/ 子目录。 本技能只是已发布 CLI 的轻量加载器；实质性内容位于公开页面、--help 和 doca-telemetry/SKILL.md 中。

加载顺序

1. 首先阅读本技能，确认用户的问题属于适用范围（遥测管道的运维侧支持工具，而非开发侧库编程）。
2. 有关三类调用、属性维度模型、逐设备支持探测、版本叠加、错误分类、可观测性界面和安全策略，请参阅能力配套文档。
3. 有关已文档化的调用，以及发现 → 解析 → 验证 → 使用工作流（install、configure、build、modify、run、test、debug、use），请参阅任务配套文档。

相关技能

• doca-telemetry/SKILL.md — 开发者侧的采集器库，其架构由此工具帮助操作员发现。在每次导出器管道排查会话中都应搭配使用。 采集器库技能会讲解采集器与导出器的区分规则、与发布者之间的架构必须匹配这一契约，以及消费者队列已满时的背压规则；此工具的作用是让操作员能够检查该契约中的架构部分。混淆该库与此工具，是初次接触遥测时最常见的错误。
• doca-public-knowledge-map/SKILL.md — 指引至 docs.nvidia.com 上的 DOCA Telemetry 指南和 DOCA Telemetry Service（DTS）页面，以及此工具的磁盘安装布局。
• doca-version/SKILL.md — DOCA 版本处理的规范规则。配套 capabilities 中的 ## Version compatibility 部分是简明的补充说明，会引导至此处查看正文，并补充工具与 doca-telemetry 库的架构版本配对规则。
• doca-setup/SKILL.md — 环境准备、安装验证，以及我还没有安装时使用公开 NGC DOCA 容器的路径。此技能假设前置条件已满足（已安装 DOCA 和遥测组件，DOCA 可见 BlueField）。
• doca-debug/SKILL.md — 跨领域的调试阶梯。Telemetry-utils 通过在运行时层展示计数器架构和每台设备的支持情况，为该调试阶梯提供信息；导出器管道回归问题通常在触及采集器／网络路径之前，就能在架构层解决。
• doca-structured-tools-contract/SKILL.md — 该套件中结构化辅助工具的检测 → 优先使用 → 回退 → 报告契约。tasks companion 中的命令附录遵循此契约。
• doca-programming-guide/SKILL.md — 适用于所有库／工具接口的通用 DOCA 编程模式，包括跨库的 DOCA_ERROR_* 分类。下游采集器／导出器代码报告相关错误时，此工具的主机端错误层会在此分类的基础上进行补充。