doca-dpa-hl-tracer

DOCA DPA 高级追踪器

示例

• “我的 DPA 内核行为不正确——应该从哪里查起？”—— 如果没有主机端的 DOCA_ERROR_*，则属于此工具的适用范围。 先采集再解码；不要一开始就使用仅分析周期数的配置。
• “TRACE 模式下，DPA 被观测开销拖慢了。”——先切换 采集窗口以及 TRACE 与 CRIT，再考虑修改内核。

说明

遵循下方的加载顺序。打开任务配套文档，了解如何配置、 运行和调试。打开功能配套文档，了解事件分类。 不要打开所有配套文件。

从这里开始： 这是一个用于调用 doca_dpa_hl_tracer 的工具技能——这是有文档说明的主机端 CLI， 用于以更高层级的形式采集 DPA 侧执行轨迹 （DPA 编程事件：内核进入／退出、同步点、 通信原语调用、RDMA WR 提交、完成事件），而非原始周期数。打开任务配套文档，从 ## configure 开始，了解模式与开销之间的取舍以及 JSON 配置布局，然后查看 ## run，了解采集 → 解码 → 渲染流程。当问题涉及 此工具实际追踪什么、它会暴露哪些 DPA 编程 事件、追踪开销与保真度之间如何权衡，或 它如何与 doca-dpa 和 doca-debug 一同融入 DPA 调试 流程时，打开功能配套文档。如果 DPA 并非适合用户问题的切入点（例如，故障发生在 主机端、故障出在 DPACC 生成的镜像中，或用户需要原始周期数），功能配套文档中的 路径选择规则会在尝试采集前引导 Agent 选择合适的路径。

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

此技能旨在回答关于 doca_dpa_hl_tracer 的各类问题，每类都附有一个完整示例。类别是核心内容；完整示例只是其中一个实例。

• “我的 DPA 内核运行结果不正确——该从哪里着手排查？”——完整示例：“我的主机端 doca_dpa_kernel_launch_update_* 已完成，但内核报告的结果不正确；主机端没有 DOCA_ERROR_*”。可通过功能说明文档中何时适合使用 DPA 端高级跟踪的判断条件，以及任务说明文档中的捕获 → 解码 → 呈现流程和应重点关注哪些 DPA 编程事件的规则来解答。
• “我的 DPA 内核运行很慢，但周期分析中看不出原因——如何查看从内核入口到首次通信调用的延迟？”——完整示例：“我的 DPA 内核运行正常，但从启动到首次提交 RDMA WR 的耗时比预期长”。可通过功能说明文档中的事件分类表，以及任务说明文档中的迭代循环来解答；该循环将跟踪开销、模式（TRACE 与 CRIT）和捕获窗口作为调优维度。
• “如何在不让观测开销拖慢 DPA 的情况下捕获跟踪信息？”——完整示例：“TRACE 模式生成的数据太多，与未启用跟踪器相比，测得的 DPA 延迟增加了 2 倍”。可通过功能说明文档中模式与开销之间的权衡，以及任务说明文档中优先使用 CRIT 的指导来解答（先仅捕获关键事件；只有在问题需要逐事件详情时才扩大到 TRACE）。
• “我的跟踪文件在运行中途被截断了——应如何配置文件大小限制？”——完整示例：“二进制跟踪文件达到 5 GB 后，捕获停止了”。可通过功能说明文档中的 log_file_max_size_in_bytes / bin_file_max_size_in_bytes / file_size_limit_policy 三项配置，以及任务说明文档中的 JSON 配置布局来解答。
• “我的安装中是否有跟踪器？它是否与匹配的 doca-dpa 库和 DPACC 编译器版本配套？”——完整示例：“我安装的跟踪器 ABI 是否与 DPACC 刚生成的 DPA 映像兼容？”。可通过功能说明文档中的版本补充说明来解答，该说明会指向规范的 doca-version 链，并补充跟踪器 ↔ doca-dpa 库 ↔ DPACC 编译器的匹配规则。
• “捕获文件看起来是空的／解码失败了——是安装损坏、没有触发事件，还是跟踪对象选错了？”——完整示例：“doca_dpa_hl_tracer 已运行并写入文件，但解析器显示事件数为 0”。可通过功能说明文档中的分层错误分类（安装／设备绑定／DPA 映像是否已插桩／捕获窗口／解码与 ELF 不匹配／开销饱和／版本／跨层问题），以及任务说明文档中的分层排查流程来解答。

受众

这项技能面向外部开发者、平台运维人员，以及已通过 doca-dpa 启动 DPA 侧工作负载、现在需要更高层次地了解 DPA 内核在网络上的实际行为的 AI Agent——包括 DPA 编程事件顺序、同步间隙、通信调用延迟、RDMA-WR／完成时序，而无需深入到原始周期计数器。具体包括：

• 能从主机侧顺利启动内核，但内核的结果错误或 DPA 侧性能低于预期，并且在排查问题之前需要获取 DPA 侧真实情况的 DPA 开发者。
• 运行使用 DPA 的工作负载（从加速器卸载 RDMA、通过 doca-pcc 实现自定义 CC 算法），并且需要在不为应用添加检测的情况下，将回归问题定位到 DPA 侧的平台运维人员。
• 作为主机侧 doca-dpa 排查流程的证据，生成 DPA 侧跟踪报告的 AI Agent；此时主机侧报告完成情况正常，但 DPA 侧行为有误。

它不面向调试跟踪器二进制本身的用户，不能替代实时公开的 DOCA DPA Tools 指南，也不适合想要学习如何编写 DPA 内核的用户（这类用户应参阅 doca-dpa 及公开的 DOCA DPA／DPACC／DPA-Comms／DPA-Verbs 指南），也不适合进行原始的逐指令周期分析（这是不同的功能和工具——请通过 doca-public-knowledge-map ## DOCA tools 获取相应资源）。

跟踪器以命令行二进制文件形式随附于 /opt/mellanox/doca/tools/，而不是供链接使用的库。此技能与套件中的其他部分一样，采用 kind: tool 三文件结构，以便在库、服务和工具之间统一 Agent 的任务动词约定。

语言范围

doca_dpa_hl_tracer 是一个 C++ 主机侧命令行工具。它的输入包括 JSON 配置文件、DPA 侧 ELF（由 DPACC 生成的 doca_dpa_app 类映像），以及已由主机侧 doca-dpa 生命周期启动的运行中 DPA 侧工作负载。它的输出是二进制跟踪文件（bin_file）和人类可读的日志文件（log_file）。本技能的工作流指导与语言无关——它跟踪的 DPA 侧工作负载可以是由 DPACC 编译的 C 代码，也可以是 DPACC 接受的任何其他 DPA 翻译单元——并通过 doca-public-knowledge-map 将特定语言的问题引导至公开的 DPA／DPACC 指南。

何时加载此技能

当用户需要，或 Agent 需要在安装了 DOCA 的真实主机上，对主机可见的带 DPA 处理器的 BlueField 调用 doca_dpa_hl_tracer，且主机端 doca-dpa 生命周期已至少启动过一次 DPA 工作负载时，加载此技能。具体包括：

• 捕获 DPA 侧跟踪记录，以便在主机端 doca-dpa 生命周期报告正常完成的情况下，定位 DPA 内核结果错误或顺序错误的行为。
• 捕获 DPA 侧跟踪记录，以便定位 DPA 侧性能差距（内核入口到首次通信的延迟、RDMA WR 提交到完成的间隔、同步点停留时间），其粒度高于原始周期计数。
• 根据错误与开销之间的权衡以及可用捕获窗口，选择 TRACE 或 CRIT 捕获模式。
• 调整 JSON 配置（线程优先级、核心亲和性、文件大小限制、文件大小限制策略），避免捕获本身对工作负载造成的影响超过正在调查的问题。
• 根据匹配的 DPA 侧 ELF 解码捕获的 bin_file，以呈现人类可读的事件流。
• 捕获副作用受限的跟踪记录，作为主机端 doca-dpa 阶梯步骤的前置证据。

不要将此技能用于一般 DOCA 入门、DPA 侧编程模型问题、原始周期分析或 DOCA / DPACC 安装。遇到这些情况，请转到 doca-public-knowledge-map、doca-dpa 或 doca-setup。

此技能提供的内容

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

• capabilities 配套文件——介绍 doca_dpa_hl_tracer 捕获的内容：DPA 编程事件分类（内核进入 / 退出、同步点、通信原语调用、RDMA WR 提交和完成排空）、两种有文档说明的捕获模式（TRACE 用于完整的逐事件捕获，CRIT 仅用于关键事件）、跟踪开销与保真度之间的权衡、配置文件结构（接收器 / 二进制写入器 / 文件写入器 / 打印线程及其优先级和核心亲和性、文件大小限制、file_size_limit_policy）、捕获窗口与工作负载必须正在运行这一不变量、用于解码的 ELF 必须与镜像匹配这一规则、版本可用性对应关系（跟踪器 ↔ doca-dpa 库 ↔ DPACC 编译器）、分层错误分类（安装 / 设备绑定 / 镜像是否经过插桩 / 捕获窗口 / 解码 / 开销饱和 / 版本 / 跨领域）、可观测性范围（二进制跟踪文件 + 日志文件 + 工具自身的 stderr），以及安全策略（捕获范围有限；跟踪不是生产环境中的可观测性手段）。
• tasks 配套文件——针对适用任务动词提供分步工作流：install（转到主机端 DOCA 安装和 DPA 前置条件）、configure（模式 + JSON 配置布局 + 捕获窗口）、build（转到安装——随附的是二进制文件，DPA 侧应用由用户使用 DPACC 构建）、modify（拒绝——不要修改二进制文件；改为修改 JSON 配置和调用方式）、run（使用 --mode、--config-file、--output-file 的捕获流程）、test（迭代调整模式、窗口和开销）、debug（逐项检查错误分类）、use（在 doca-dpa 调试会话中使用已解码的跟踪记录），以及 Deferred task verbs 块。

此技能假设主机已在标准位置安装 DOCA，主机可见配备 DPA 处理器的 BlueField，DPACC 编译器已安装且版本与主机端 DOCA 匹配，DPA 侧应用镜像（跟踪器据此解码的 ELF）已在磁盘上，且与 doca-dpa 生命周期加载的镜像一致；同时，操作员拥有 DOCA DPA Tools 公共指南要求的权限。

此技能有意不提供的内容

此技能是Agent 指南，不是示例或脚本合集。为明确界限，此技能有意不包含以下内容，且不应通过拉取请求添加：

• 公共 DOCA DPA Tools 页面和 --help 文档中未提及的具体标志字符串、事件名称或模式标记。 DPA 编程事件列表会随版本迭代而变化；已安装二进制文件的 --help 是权威清单。
• 预先制作的示例跟踪记录或预期事件时序。 跟踪输出因工作负载、DPA 映像、BlueField 和固件而异；绑定到某一套配置的记录示例会误导其他地方的操作人员。
• 任何语言的包装器、解析器或渲染脚本，用于处理二进制跟踪格式。该格式已有文档；想针对它编写脚本的用户应阅读实时指南，并根据其安装的版本编写解析器。
• 基于单条跟踪记录得出的具体调优建议。 DPA 侧的性能决策（移动同步操作、批处理通信调用、更改启动参数）取决于工作负载；此技能规定如何捕获和读取跟踪记录，但不会在没有用户自行分析的情况下，将捕获到的间隔转化为重写内核的建议。
• samples/ 或 reference/ 子目录。 这是已发布 CLI 的轻量加载器；实质性内容位于公共页面、--help 和 doca-dpa 中。

加载顺序

1. 首先阅读此技能，确认用户的问题属于其适用范围（DPA 侧的高级跟踪，不包括 DPA 侧编程和原始周期分析）。
2. 有关事件分类、捕获模式、开销权衡、JSON 配置布局、版本覆盖、错误分类、可观测性和安全策略，请参阅能力配套文档。
3. 有关已记录的调用方式以及捕获 → 解码 → 渲染工作流 — install、configure、build、modify、run、test、debug、use — 请参阅任务配套文档。

相关技能

• doca-dpa — 主机端 DPA 控制库，其已加载的应用映像是 跟踪器的捕获对象。在每次 DPA 调试会话中 配合使用：doca-dpa 启动工作负载；跟踪器捕获 工作负载在 DPA 编程事件层的行为。将该库与跟踪器混为一谈， 是初次接触 DPA 调试时最常见的错误。
• doca-debug — 跨领域的 调试阶梯。在得出任何 DPA 侧性能或正确性结论之前， 跟踪器会在 运行时 层提供 DPA 侧的事实依据。
• doca-public-knowledge-map — 指向 docs.nvidia.com 上公开的 DOCA DPA Tools 页面 及其余公开 DOCA 文档集。
• doca-version — DOCA 版本处理的规范规则。功能配套文档中的 ## Version compatibility 部分是简明的补充说明，详细内容请参阅此处， 并补充了 跟踪器 ↔ doca-dpa 库 ↔ DPACC 编译器 的匹配规则。
• doca-setup — 环境 准备、安装验证、DPACC 编译器的安装与验证、BlueField 模式（必须先 暴露 DPA 处理器，跟踪才有意义），以及 尚未安装 的路径， 其中使用公开的 NGC DOCA 容器。
• doca-structured-tools-contract — 此工具包针对结构化辅助工具的 detect → prefer → fall back → report 契约。任务配套文档中的命令附录遵循此契约。
• doca-programming-guide — 所有库 / 工具接口共用的通用 DOCA 编程模式，包括跨库的 DOCA_ERROR_* 分类；当主机端 doca-dpa 调用同时失败时，本工具主机端错误层会在此基础上进行扩展。

DPA 侧的配套库 doca-dpa-comms（DPA 内核自身调用的通信原语）和 doca-dpa-verbs（DPA 内核自身调用的 RDMA verbs） 是不同的制品，跟踪器的 DPA 编程事件会明确显示其名称；如需了解 DPA 侧编程模型本身，请通过 doca-public-knowledge-map 查阅公开的 DOCA DPA-Comms 和 DPA-Verbs 指南，以及随附的 /opt/mellanox/doca/samples/doca_dpa/ 示例。 本工具用于跟踪它们的使用情况；不会重新定义它们。