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_bpu_trace.cfg        # 开启bpu trace的perfetto配置文件
		│   ├── ucp_in_process.cfg       # in_process模式的perfetto配置文件
		│   ├── ucp_in_process.json      # in_process模式的ucp配置文件
		│   ├── ucp_system.cfg           # system模式的perfetto配置文件
		│   └── ucp_system.json          # system模式的ucp配置文件

环境变量

环境变量	取值范围	默认值	说明
`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`	创建模型推理任务
`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 \
    --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 只是其中的一个数据源，因此需要运行 tracebox 相对应的指令来完成 trace 的捕获。

操作步骤

运行 Perfetto 后台进程。

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

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

触发数据抓取。

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

另起一个终端，配置 UCP 环境变量。

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

# 开启 perfetto 功能。
export HB_UCP_ENABLE_PERFETTO=true

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

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

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

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

BPU Trace

在 system 模式下支持抓取 BPU trace，只需在 perfetto 配置文件中加入 BPU trace 的数据源即可，ucp_bpu_trace.cfg 中已默认添加了BPU trace数据源，具体配置项如下所示：

data_sources: {
    config {
        name: "linux.sys_stats"
        sys_stats_config {
            bputrace_period_ms: 500
        }
    }
}

bputrace_period_ms 用于设置读取BPU trace的周期，您可根据实际使用场景调整该参数，当BPU负载较大时，可以适当缩短读取周期，避免发生因读写速度不匹配导致的trace数据被覆盖的问题。

为了展示多个模型推理过程中的 BPU trace，这里提供了一个多进程应用的示例。除了启动的运行程序有所不同外，其余的步骤与前一章节相同。

./hrt_model_exec perf                        \
    --model_file resnet50_224x224_nv12.hbm   \
    --frame_count 50                         \
    --thread_num 1 &                         \

./hrt_model_exec perf                        \
    --model_file googlenet_224x224_nv12.hbm  \
    --frame_count 50                         \
    --thread_num 1                           \

BPU Trace 的可视化需要使用地平线定制开发的 hbperfetto 工具进行打开，您可以通过联系地平线系统软件技术支持人员来获取该工具。使用 hbperfetto 打开trace文件的效果如下图所示：

BPU Trace中所呈现的不同模型推理任务的调度情况如下图所示：

hbperfetto 支持 UCP trace 和 BPU trace 的关联。以下图示展示了从 UCP 模型推理任务的创建，提交，调度执行，直至任务完成执行并最终释放的完整流程。

此外，您可通过SQL查询BPU trace的原始数据。

select * from bpu_trace

Long Trace 配置

默认情况下，Perfetto将trace数据存储在内存中的缓冲区，直至trace会话终止时，才会将缓冲区的数据转储至文件。若trace数据量超出缓冲区容量，则无法保证数据的完整性。

Perfetto支持周期性地将缓冲区的数据写入到文件中，只需在trace配置文件中增加以下字段即可。

配置项	类型	说明
write_into_file	bool	`true` 开启日志周期性写入到文件，默认不开启。
file_write_period_ms	uint32	设置写入文件的周期，默认值为`5s`。您可根据每秒生成数据的大小和trace缓冲区容量来设置合适的写入周期。
max_file_size_bytes	uint64	设置trace文件的最大值，当超过该值后，trace将自动终止，默认无限制。

常用数据源介绍

事件类型	数据源名称	hbperfetto定制	配置	说明
应用的track事件	`track_event`	否	`track_event_config`	用于抓取应用程序通过调用perfetto sdk api进行埋点的数据。
ftrace	`linux.ftrace`	否	`ftrace_config`	通过ftrace_events指定抓取的事件，比如`sched/sched_switch`，具体支持的事件可通过`/sys/kernel/tracing/available_events`查看，`ftrace_config` 的详细说明请参考 FtraceConfig。
系统内存	`linux.sys_stats`	否	`sys_stats_config`	通过 `meminfo_period_ms` 设置采样周期，`meminfo_counters`设置抓取的数据类型，比如`MEMINFO_MEM_AVAILABLE`，`sys_stats_config` 的详细说明请参考 SysStatsConfig。
进程内存	`linux.process_stats`	否	`process_stats_config`	通过 `proc_stats_poll_ms` 设置采样周期，`process_stats_config` 的详细说明请参考 ProcessStatsConfig。
CPU占用	`linux.sys_stats`	否	`sys_stats_config`	通过 `stat_period_ms` 设置采样周期。
perf	`linux.perf`	否	`perf_event_config`	记录进程调用栈和perf计数，`perf_event_config` 的详细说明请参考 PerfEventConfig。
DDR带宽	`linux.sys_stats`	是	`sys_stats_config`	记录ddr读写带宽，通过 `ddrinfo_period_ms` 设置采样周期。
ION内存	`linux.sys_stats`	是	`sys_stats_config`	记录ION内存信息，通过 `ion_period_ms` 设置采样周期。
BPU占用	`linux.sys_stats`	是	`sys_stats_config`	记录BPU占用率，通过 `bpuinfo_period_ms` 设置采样周期。
BPU trace	`linux.sys_stats`	是	`sys_stats_config`	记录BPU trace信息，通过 `bputrace_period_ms` 设置采样周期。

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 \
    --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：

#UCP Trace 使用说明

#环境变量

#UCP Trace 记录点

#任务 Trace 记录点

#算子 Trace 记录点

#Perfetto Trace

#概述

#配置文件

#UCP Trace 配置文件

#参数描述

#示例 1：in_process 模式

#示例 2：system 模式

#Perfetto 配置文件

#示例：ucp_in_process.cfg

#使用示例

#in_process 模式

#操作步骤

#system 模式

#操作步骤

#BPU Trace

#Long Trace 配置

#常用数据源介绍

#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 模式

操作步骤

BPU Trace

Long Trace 配置

常用数据源介绍

Chrome Trace

使用示例