doca-telemetry-exporter

DOCA Telemetry Exporter

示例

• “从我的 DOCA 应用发布计数器。”——这属于本指南的范围。按先架构、后数据源的顺序进行；不要在此处配置 DTS。
• “报告事件时出现 BAD_STATE。”——先检查生命周期顺序，再修改报告调用。

说明

遵循下文的加载顺序。需要配置／发布／调试时，打开任务配套文件。需要了解发布方式时，打开功能配套文件。不要打开所有配套文件。

从哪里开始：本技能假设 DOCA 已安装，且用户正在实际操作 telemetry-exporter——从使用 DOCA 的程序向外部使用方发送结构化应用遥测数据（计数器／事件）。如果用户想要执行某项操作（配置／构建／修改并重新构建／运行／测试／调试），请打开任务配套文件；如果用户想了解此安装中的导出器能表达什么，请打开功能配套文件。如果用户尚未安装 DOCA，请先转到 doca-setup/SKILL.md。 如果用户不确定自己需要的是此库还是 DOCA Telemetry Service（接收端），请先阅读功能配套文件中的导出器与服务规则，再进行任何配置。

**此库不是 DOCA Core 上下文。**导出器没有 doca_ctx_start()，也没有针对每个 doca_devinfo 的能力查询系列（其 doca_caps 转储是桩实现）。其生命周期为 schema_init → 配置导出器 → 注册类型 → schema_start → source_create → source_start → 报告 → 刷新 → 销毁。

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

此技能旨在回答以下类别的 telemetry-exporter 问题，每类附带一个完整示例。Agent 应将类别视为核心内容——完整示例只是其中一个实例。

• “我需要哪个库——exporter 还是 telemetry 服务？”——完整示例：“我想让 DOCA Flow 程序向下游收集器发布每秒处理的数据包计数器——应该链接哪个 DOCA 组件？” 由 ## Capabilities and modes 中的角色划分表 + 路径选择要点回答，两者都指出 doca-telemetry-exporter 是应用程序要链接的发布方，并将接收 / 消费端引导至此技能范围之外。
• “如何从 DOCA 程序发出我的第一个结构化事件？”——完整示例：“从我的 DOCA Flow 应用发出一条 packets_processed 事件记录”。由 ## Capabilities and modes 中的 schema → source 生命周期对象表 + ## configure + ## run 第 3 步（批量操作前先进行文件写入冒烟测试）中的工作流回答，从 telemetry_export/ 示例开始。
• “我需要哪种发布方式——类型化事件、指标、OTLP 日志还是 NetFlow？”——完整示例：“我想要带标签的每接口数据包计数器和带宽仪表”。由 ## Capabilities and modes 中的发布方式表回答（该需求对应 Metrics API——_metrics_add_counter / _add_gauge——以及 telemetry_export_metrics/ 示例），并由 ## modify 中的示例映射提供补充说明。
• “我的 report 调用返回 DOCA_ERROR_BAD_STATE——我哪里做错了？”——完整示例：“doca_telemetry_exporter_source_report 第一次调用就返回 BAD_STATE”。由 ## Error taxonomy 中的 BAD_STATE 行回答（source 从未启动，或者写入 / 刷新时缺少 OTLP context）+ ## configure 中的生命周期顺序说明。请注意，此 API 不会返回 DOCA_ERROR_AGAIN，也不会返回 DOCA_ERROR_NOT_FOUND。
• “程序报告了，但 DTS / 收集器什么也没收到——我该从哪里开始排查？”——完整示例：“我的 report 返回成功，但 DTS 日志是空的”。由 ## Safety policy 中先启动接收方的分阶段流程 + ## test 中的文件写入冒烟测试和 check_ipc_status 步骤回答（先通过文件写入验证发布端，再确认 IPC 状态为 CONNECTED 且接收方已启动）。
• “如何确认 exporter 已安装且传输正常？”——完整示例：“我的 DOCA 3.x 安装中是否有 exporter，IPC 是否真的已连接到 DTS？”。由 ## Version compatibility 中的版本兼容性补充说明回答（交叉链接到 doca-version/SKILL.md 中的检测流程），并遵循 ## Capabilities and modes 中准确的内省规则（使用 doca_telemetry_exporter_check_ipc_status，而不是设备能力查询）。

受众

本技能面向通过 DOCA Telemetry Exporter 构建可发出结构化遥测数据的应用程序的外部开发者，也就是说，其应用代码会调用 doca_telemetry_exporter_*（直接使用 C/C++，或通过其他语言的 FFI/绑定），将其使用 DOCA 的程序中的计数器、量表和事件发布到外部遥测数据使用方。本技能不面向为 DOCA Telemetry Exporter 本身做贡献的 NVIDIA 开发者，也不面向构建遥测数据接收／聚合服务的用户（DOCA Telemetry Service 是独立的 DOCA 服务，有自己的公开指南，可通过 doca-public-knowledge-map/SKILL.md 查阅）。

**语言范围。**DOCA Telemetry Exporter 以 C 库的形式提供，pkg-config 模块名称为 doca-telemetry-exporter。随附的示例使用 C 编写。C 和 C++ 使用者是典型场景；任务配套材料中的详细示例也假设使用这一路径。其他语言的使用者（Rust、Go、Python，等等）通过 FFI 或特定语言绑定使用相同的 *.so；在这种情况下，本技能的作用是确保以下内容不受语言影响：区分 exporter 与 service、schema → source 生命周期、通过传输而非 caps 进行发现的规则、权限规则（与应用使用相同的用户）、基于缓冲和刷新进行交付的模型，以及错误分类指导；并引导 Agent 将公开的 C ABI 视为权威接口，任何包装层最终都会调用该接口。

何时加载此技能

当用户正在使用任意语言进行 DOCA Telemetry Exporter 实际开发时，加载此技能。具体包括：

• 为应用将要发出的事件定义 doca_telemetry_exporter_schema（字段名称和字段类型），并在发布任何事件之前，先将其注册到 exporter。
• 创建一个或多个 doca_telemetry_exporter_source 实例，以表示应用中不同的逻辑遥测数据源（例如，每个工作线程／每个流水线阶段各一个数据源）。
• 根据应用要报告的内容，选择合适的发布接口——类型化结构化事件（_source_report）、不透明事件（_source_opaque_report）、Metrics API（计数器／量表／直方图）、OTLP 日志，或 NetFlow 关联 API。
• 确认 exporter 的安装和传输状况（此库没有 doca_devinfo caps 查询系列，也没有 doca_caps 数据）：使用 doca_telemetry_exporter_check_ipc_status 检查 IPC 是否存活，使用 _source_get_opaque_report_max_data_size 获取不透明负载大小上限，并使用 _schema_get_* 配置 getter。
• 排查 exporter 调用返回的 DOCA_ERROR_*（BAD_STATE 生命周期顺序问题、INVALID_VALUE 类型／标签不匹配、NO_MEMORY、INITIALIZATION、UNKNOWN 后端错误），以及返回给应用的每次调用状态。
• 在 Telemetry Exporter 与相邻选项之间做出选择（如果 stdout／结构化日志转发已足够，则使用 doca_log；如果用户需要非 DOCA 感知型接收端，则使用 Prometheus 客户端库；如果用户需要向应用内实时订阅事件，则使用 doca-comch/SKILL.md——exporter 仅支持发布，且为单向传输）。
• 设计或扩展封装 exporter C ABI 的非 C 绑定（Rust、Go、Python，等等），确保遵守 exporter 与 service 的区分、schema → source 生命周期、权限策略、基于缓冲和刷新的交付模型，以及传输探查和错误处理规则。

对于一般性的 DOCA 入门、安装 DOCA 本身、接收遥测数据的服务（DOCA Telemetry Service 有自己的公开指南，可通过 doca-public-knowledge-map/SKILL.md 查阅），或非 exporter 库相关问题，不要加载此技能。对于这些情况，请使用 doca-public-knowledge-map/SKILL.md。

此技能提供的内容

这是一个轻量加载器。正文仅保留用于判断下一步应查看哪个文件的指引。实质性的导出器专属内容位于两个配套文件中：

• capabilities 配套文件——说明此安装中的导出器能够表达什么：导出器与服务的职责划分规则、对象族（doca_telemetry_exporter_schema → _type/_field → _source，包含 schema → source 的生命周期）、四种发布方式（类型化事件 / 不透明事件 / Metrics API / OTLP 日志）以及 NetFlow 同级 API、传输而非能力的内省规则（check_ipc_status、_get_opaque_report_max_data_size、_schema_get_*——不含 doca_caps 数据，不进行设备能力查询）、导出器错误分类（映射到跨库的 DOCA_ERROR_* 集合，并注明此接口没有 AGAIN，也没有 NOT_FOUND）、可观测性接口（每次调用的状态 + IPC 状态 + 文件写入检查 + 接收端作为端到端信号）、对应用相同用户权限的安全策略以及先启动接收端的分阶段流程，还有避免使用 doca_log 和 doca-comch 的路径选择规则。
• tasks 配套文件——针对六个适用的导出器动词提供分步工作流：configure、build、modify（之后重新构建）、run、test、debug。此外还有一个 Deferred task verbs 区块，将范围外的问题指向合适的后续技能。

此技能假定主机已在标准位置安装 DOCA，应用以能够写入导出器所配置遥测传输的用户身份运行，并且可访问的遥测接收端已在导出器启动前启动。它不涵盖安装 DOCA——安装流程请参阅 doca-setup/SKILL.md——也不涵盖配置或运行遥测接收服务；该服务是独立的 DOCA 服务，有自己的公开指南。

此技能有意不提供的内容

此技能提供的是Agent 指引，而不是示例或模板合集。为明确范围，此技能有意不包含以下内容，且不应通过拉取请求添加：

• 任何语言编写的预先完成的 DOCA Telemetry Exporter 应用源代码。 已验证的导出器源代码是随产品提供的 C 示例，位于 /opt/mellanox/doca/samples/doca_telemetry_exporter/。Agent 的职责是引导用户找到这些文件，并通过 doca-programming-guide/SKILL.md 中通用的示例修改工作流，对其进行最小差异修改，再叠加 ## modify 中针对导出器的专属覆盖规则。
• 遥测使用者 / 收集器 / 接收服务。 DOCA Telemetry Service 是独立的 DOCA 服务，有自己的公开指南；请通过 doca-public-knowledge-map/SKILL.md 转到相应指南。本技能仅涉及发布端。
• 存放在技能目录中的独立构建清单（meson.build、CMakeLists.txt、Cargo.toml 等）。Agent 应在用户的项目目录中，针对用户已安装的 DOCA 构建清单，其中 pkg-config --modversion doca-telemetry-exporter 是事实依据。
• 任何类型的 samples/、bindings/ 或 reference/ 子目录。 即使在此技能目录树中放置的模拟或不完整工件标注为“reference”，也会造成误导：用户会将其视为可构建内容。

加载顺序

1. 首先阅读此技能，确认用户的问题属于适用范围。
2. 有关导出器与服务的区分规则、对象系列、schema → source 生命周期、四种发布方式 + NetFlow、传输层而非容量的自省规则、错误分类（注意：没有 AGAIN，也没有 NOT_FOUND）、可观测性、安全策略，以及避开 doca_log / comch 的路径选择规则，请参阅 capabilities 配套技能。
3. 有关分步工作流——配置、构建、修改、重新构建、运行、测试、调试，请参阅 tasks 配套技能。

两个配套文件相互交叉链接；它们还会链接到 doca-version/SKILL.md，以获取规范的版本处理规则；并会在正确答案是“查阅公开文档或已安装的软件包布局”而非“导出器专属指南”时，链接到 doca-public-knowledge-map/SKILL.md。

相关技能

• doca-public-knowledge-map/SKILL.md — 所有公开 DOCA 文档来源及已安装 DOCA 软件包磁盘布局的路由表。导出器的公开指南 URL 为 https://docs.nvidia.com/doca/sdk/DOCA-Telemetry-Exporter/index.html； 磁盘上的示例位于 /opt/mellanox/doca/samples/doca_telemetry_exporter/ 下。DOCA Telemetry Service（即接收方，不在此处的范围内）是单独的指南，可通过同一张路由表找到。
• doca-setup/SKILL.md — 环境准备、 安装验证、传输侧可达性检查，以及使用公开 NGC DOCA 容器的我还没有安装路径。此技能假设其前置条件均已满足（尤其是应用程序用户能够写入遥测传输）。
• doca-version/SKILL.md — 规范的 DOCA 版本处理规则。此技能中的 ## Version compatibility 会链接到四方匹配规则 + 检测链，并补充导出器专属的叠加规则。
• doca-structured-tools-contract/SKILL.md — 此套件的结构化工具优先级规则（检测 / 优先使用 / 回退 / 报告）。tasks 配套技能中的 Command 附录遵循此约定。
• doca-programming-guide/SKILL.md — 适用于每个库的通用 DOCA 编程模式：规范的 pkg-config + meson 构建模式、通用的“先修改已提供的示例”首个应用程序工作流、通用生命周期、跨库的 DOCA_ERROR_* 错误分类，以及程序侧调试顺序。此技能在此基础上补充导出器专属内容。
• doca-comch/SKILL.md — 当用户需要将实时事件订阅发送回应用程序内部时（主机 ↔ DPU 控制平面消息传递），应使用的正确原语。导出器仅支持发布 / 单向传输；若实际需求是订阅，此技能的路径选择规则会将用户引导至此处。
• doca-debug/SKILL.md — 跨领域调试步骤（安装 / 版本 / 构建 / 链接 / 运行时 / 程序 / 驱动程序）。导出器专属的调试问题（接收方未启动、生命周期顺序 BAD_STATE、类型 / 标签 INVALID_VALUE、未启用不透明路径）会叠加在这些步骤之上。