中文

UCP Trace 使用说明

UCP trace 通过在 UCP 执行的关键路径上嵌入 trace 记录，提供深入分析 UCP 应用程序调度逻辑的能力。在出现性能异常时，可以通过分析UCP trace，快速找到异常发生的时间点。

UCP trace 提供了两种 trace 后端选项：Perfetto Trace 和 Chrome Trace。您可以通过设置环境变量，在这两者之间进行选择，以满足您特定的性能跟踪需求。

Perfetto Trace可以获取到 UCP 记录的 trace，以及系统状态， ftrace 等信息。
Chrome Trace只能获取 UCP 记录的 trace ，主要用于分析 UCP 本身的调度逻辑。

UCP trace 工具和配置文件位于 samples/ucp_tutorial/tools 路径下，目录结构为：

	tools/
	└── trace                            # trace工具
		├── catch_trace.sh               # chrome trace捕获脚本
		├── configs                      # 参考配置文件
		│   ├── ucp_in_process.cfg       # in_process模式的perfetto配置文件
		│   ├── ucp_in_process.json      # in_process模式的ucp配置文件
		│   ├── ucp_system.cfg           # system模式的perfetto配置文件
		│   └── ucp_system.json          # system模式的ucp配置文件
		├── perfetto                     # 触发trace抓取的工具
		├── traced                       # trace服务程序
		└── traced_probes	             # trace数据抓取程序

环境变量

环境变量	取值范围	默认值	说明
`HB_UCP_ENABLE_PERFETTO`	true，false	false	是否启用 Perfetto trace，true 启动，false 不启动，默认不启动。
`HB_UCP_PERFETTO_CONFIG_PATH`	Perfetto 配置文件路径	""	指定 pefetto 配置文件的路径，默认为空，如果不需要 UCP 初始化 perfetto，则可不配置该环境变量。
`HB_UCP_TRACE_LOG_LEVEL`	[0, 6]	6	指定 UCP Trace 日志等级，默认为 6，不输出。
`HB_UCP_USE_ALOG`	true，false	false	是否启用 alog sink，true 启动，false 不启动，默认不启动。启动 alog sink 之后会输出日志到 alog buffer，使用 logcat 抓取日志，同时关闭日志输出到终端。

注解

Perfetto trace的优先级更高，如果export HB_UCP_ENABLE_PERFETTO=true 的同时 export UCP_TRACE_LOG_LEVEL=0，那么只启动 Perfetto trace，忽略UCP trace日志级别。

UCP Trace 记录点

UCP 在应用程序 API 及内部关键调度路径嵌入了 trace 记录，其中包括任务 trace 记录和算子 trace 记录。

任务 Trace 记录点

名称	说明
`hbDNNInfer`	创建模型推理任务
`hbDNNRoiInfer`	创建 ROI 模型推理任务
`hbVPxxx`	创建视觉处理任务
`hbHPLxxx`	创建高性能计算任务
`hbUCPSubmitTask`	任务提交
`${TaskType}::Wait`	等待任务执行结束
`TaskSetDone`	通知任务执行完成
`hbUCPReleaseTask`	任务释放

算子 Trace 记录点

名称	说明
`SubmitOp`	算子提交
`OpInfer`	算子开始执行
`OpFnish`	算子执行结束

Perfetto Trace

概述

Perfetto 是 Google 开发和开源的系统性能分析工具，能够收集来自不同数据源的性能数据，同时提供了 Perfetto UI 用于数据的可视化和分析。更多 perfetto 的详细信息，请参考 Perfetto 官方文档。

配置文件

UCP Trace 配置文件

用于配置 UCP 如何使用 Perfetto，您可以通过环境变量HB_UCP_PERFETTO_CONFIG_PATH来指定。

参数描述

参数	类型	取值范围	说明
`backend`	string	"in_process"，"system"	in_process 表示进程内模式，进程内直接保存 perfetto trace 到文件。system 表示系统模式，由后台服务 traced，traced_probe 统一进行 trace 捕获。
`trace_config`	string	perfetto 的配置文件路径	backend 设置为"in_process"时有效，为 protobuf 文本格式的配置文件。

注解

UCP trace 配置文件非必须指定，如果您的应用程序已经初始化了Perfetto，那么只需要 export HB_UCP_ENABLE_PERFETTO=true 即可开启Perfetto。

示例 1：in_process 模式

{
    "backend": "in_process",
    "trace_config": "ucp_in_process.cfg"
}

示例 2：system 模式

{
    "backend": "system"
}

注解

backend 选择system时，无需单独为 UCP 指定trace_config。

Perfetto 配置文件

关于 Perfetto 配置文件的详细信息可以参考 Perfetto TraceConfig Reference。 UCP 提供了参考配置文件 ucp_in_process.cfg 和ucp_system.cfg ，您可根据应用场景进行修改。

示例：ucp_in_process.cfg

# Enable periodic flushing of the trace buffer into the output file.
write_into_file: true

# Output file path
output_path: "ucp.pftrace"

# Sampling duration: 10s
duration_ms: 10000

# Writes the userspace buffer into the file every 2.5 seconds.
file_write_period_ms: 2500

buffers {
  # buffer size
  size_kb: 65535
  # DISCARD: no new sampling data will be stored when the storage is full.
  # RING_BUFFER: old sampling data will be discarded and new data will be stored when the storage is full.
  fill_policy: RING_BUFFER
}

# UCP data source
data_sources: {
    config {
        name: "track_event"
        track_event_config {
           enabled_categories: "dnn"
        }
    }
}

使用示例

in_process 模式

in_process 模式下只能抓取 UCP 进程内的 trace 信息，可以不用启动 perfetto 的后台进程。

操作步骤

配置环境变量。

# 指定 ucp perfetto 配置路径。
export HB_UCP_PERFETTO_CONFIG_PATH=ucp_in_process.json

# 开启 perfetto 功能。
export HB_UCP_ENABLE_PERFETTO=true

注解

ucp_in_process.json中指定了 Perfetto 的配置文件ucp_in_process.cfg，其中output_path指定了 trace 文件的输出路径。由于 Perfetto 不支持直接覆盖原有的 trace 文件，若该文件已经存在，则需要先将其删除。

运行 UCP 应用程序，这里以hrt_model_exec为例。

由于指定的文件路径是相对路径，因此trace配置文件和脚本需要放置在运行程序的同级目录下。同时，需要确保在同一个shell环境中配置环境变量和运行程序。

./hrt_model_exec perf                      \
    --model_file resnet50_224x224_nv12.hbm \
    --input_file zebra_cls.jpeg            \
    --frame_count 1000                     \
    --thread_num 8

生成的 trace 保存在 ucp.pftrace，您可以使用 Perfetto UI 打开。

在时间线上点击创建的任务，可以看到任务从创建到释放的完整调度流程。

Perfetto UI 常用操作如下，更详细的操作说明，请参考help界面。

操作	说明
`w` 或 ctrl+鼠标滚轮上滑	放大
`s` 或 ctrl+鼠标滚轮下滑	缩小
`a` 或向左拖动上方的时间条	左移
`d` 或向右拖动上方的时间条	右移
`?`	打开 help 界面

system 模式

system 模式下，UCP trace 只是其中的一个数据源，因此需要运行 Perfetto 的后台进程来完成 trace 捕获，同时通过运行命令行工具perfetto来配置和触发 trace 捕获。

操作步骤

配置环境变量。

# 指定 ucp perfetto 配置路径。
export HB_UCP_PERFETTO_CONFIG_PATH=ucp_system.json

# 开启 perfetto 功能。
export HB_UCP_ENABLE_PERFETTO=true

运行 Perfetto 后台进程。

# 启动 trace 服务。
# 只需要启动一次，如果已经启动，则不需要再次启动。
./traced --background

# 运行数据捕获服务。
# 只需要启动一次，如果已经启动，则不需要再次启动。
./traced_probes --background --reset-ftrace

触发数据抓取。

# -c：指定perfetto 配置文件。
# -o：指定输出trace数据文件路径。
./perfetto --txt -c ucp_system.cfg -o ucp.pftrace

运行 UCP 应用程序，这里以hrt_model_exec为例。

为了能够抓取完整的数据，需要确保hrt_model_exec执行结束前，perfetto进程未退出。

./hrt_model_exec perf                      \
    --model_file resnet50_224x224_nv12.hbm \
    --input_file zebra_cls.jpeg            \
    --frame_count 1000                     \
    --thread_num 8

生成的 trace 保存在 perfetto 命令指定的输出文件 ucp.pftrace，您可以使用 Perfetto UI 打开。

Chrome Trace

Chrome trace 只支持捕获 UCP trace，不支持多数据源的捕获，多数据源的捕获请使用 Perfetto trace。Chrome trace 的特点是简单，易用，使用文本日志来记录 trace，不依赖于额外的三方库和工具。如果只关心 UCP 的调度逻辑，可以使用 Chrome trace 来进行捕获。

使用示例

配置环境变量。

# 关闭 perfetto
export HB_UCP_ENABLE_PERFETTO=false

# 设置 UCP Trace 的日志级别为 0。
export HB_UCP_TRACE_LOG_LEVEL=0

# 设置 UCP 日志保存的文件路径。
export HB_UCP_LOG_PATH=ucp_log.txt

注解

在开始新的捕获前，建议先删除旧的日志文件，避免旧的数据带来的干扰。

运行 UCP 应用程序，这里以hrt_model_exec为例。

./hrt_model_exec perf                      \
    --model_file resnet50_224x224_nv12.hbm \
    --input_file zebra_cls.jpeg            \
    --frame_count 1000                     \
    --thread_num 8

执行trace抓取脚本。

在完成trace日志的捕获后，运行UCP发布包中提供了catch_trace.sh，将原始的trace日志转换为json格式的trace文件。

# -i: 指定输入trace日志文件。
# -o: 指定输出json格式的trace日志。
./catch_trace.sh -i ucp_log.txt -o ucp_trace_task.json

# 默认以任务视角可视化trace，您也可以切换为线程视角。
# -m: 指定转换模式，task: 任务视角（默认），thread: 线程视角。
./catch_trace.sh -m thread -i ucp_log.txt -o ucp_trace_thread.json

使用 Perfetto UI 或 Chrome UI(chrome://tracing/) 打开 ucp_trace_task.json 和 ucp_trace_thread.json。

Chrome UI 打开 ucp_trace_task.json：

Perfetto UI 打开 ucp_trace_thread.json：

页面目录

hb_compile工具

QAT

模型导出

Horizon算子

视觉算法

示例

VP API手册

数据结构

功能接口

模型推理API手册

数据类型和数据结构

API接口

模型推理工具介绍

高性能算法

HPL API手册

数据结构

功能接口

数据结构

功能接口

使用框架

使用指南

示例说明

API手册

#UCP Trace 使用说明

#环境变量

#UCP Trace 记录点

#任务 Trace 记录点

#算子 Trace 记录点

#Perfetto Trace

#概述

#配置文件

#UCP Trace 配置文件

#参数描述

#示例 1：in_process 模式

#示例 2：system 模式

#Perfetto 配置文件

#示例：ucp_in_process.cfg

#使用示例

#in_process 模式

#操作步骤

#system 模式

#操作步骤

#Chrome Trace

#使用示例

UCP Trace 使用说明

环境变量

UCP Trace 记录点

任务 Trace 记录点

算子 Trace 记录点

Perfetto Trace

概述

配置文件

UCP Trace 配置文件

参数描述

示例 1：in_process 模式

示例 2：system 模式

Perfetto 配置文件

示例：ucp_in_process.cfg

使用示例

in_process 模式

操作步骤

system 模式

操作步骤

Chrome Trace

使用示例