#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 本身的调度逻辑。

#基础使用与效果展示

#Perfetto Trace

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

#in_process 模式示例

in_process 模式下只能抓取 UCP 进程内的 trace 信息，无需启动 Perfetto 后台进程。具体操作步骤如下：

1. 配置环境变量。

   # 指定 ucp perfetto 配置路径。
   export HB_UCP_PERFETTO_CONFIG_PATH=ucp_in_process.json
   
   # 开启 perfetto 功能。
   export HB_UCP_ENABLE_PERFETTO=true

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

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

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

   

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

   

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

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

#system 模式示例

system 模式下，UCP trace 只是其中的一个数据源，因此需要运行 tracebox 对应的指令来完成 trace 捕获。具体操作步骤如下：

1. 运行 Perfetto 后台进程。

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

2. 触发数据抓取。

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

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

   # 默认不指定 HB_UCP_PERFETTO_CONFIG_PATH 时，为 system 模式。
   # 如果不生效，可能是当前版本不支持自动选择，需要显式指定 system 的配置文件。
   export HB_UCP_PERFETTO_CONFIG_PATH=ucp_system.json
   
   # 开启 perfetto 功能。
   export HB_UCP_ENABLE_PERFETTO=true

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

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

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

   

#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

#Chrome Trace

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

#使用示例

1. 配置环境变量。

   # 关闭 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

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

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

3. 执行 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

4. 使用 Perfetto UI 打开 ucp_trace_task.json 和 ucp_trace_thread.json。

   Perfetto UI 打开 ucp_trace_thread.json：

   

#配置与工具说明

#工具和配置文件位置

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

  tools/
  └── trace                          # trace 工具
    ├── catch_trace.sh               # chrome trace 捕获脚本
    ├── configs                      # 参考配置文件
    │   ├── ucp_bpu_trace.cfg        # 开启 bpu trace 的 perfetto 配置文件
    │   ├── ucp_dsp_trace.cfg        # 开启 dsp 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 配置文件

#环境变量

#配置文件参数信息

#UCP trace 配置文件参数信息

#Long trace 配置文件参数信息

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

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

#配置文件模板

#UCP Trace 配置文件模板

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

in_process 模式

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

system 模式

{
    "backend": "system"
}

#Perfetto 配置文件模板

关于 Perfetto 配置文件的详细信息可以参考 Perfetto TraceConfig Reference。 UCP 提供了参考配置文件 ucp_in_process.cfg 和 ucp_system.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"
        }
    }
}

#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 数据被覆盖的问题。

#DSP Trace 配置文件模板

在 system 模式下支持抓取 DSP trace，只需在 Perfetto 配置文件中加入 DSP trace 的数据源即可。ucp_dsp_trace.cfg 中已默认添加了 DSP trace 数据源，有效配置项如下所示：

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

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

# stop vdsp fw
echo stop > /sys/class/remoteproc/remoteproc1/state

# stop or start dsp trace
echo 0 > /sys/devices/virtual/misc/vdsp0/vdsp_ctrl/trace_switch
echo 1 > /sys/devices/virtual/misc/vdsp0/vdsp_ctrl/trace_switch

# check dsp trace status
cat /sys/devices/virtual/misc/vdsp0/vdsp_ctrl/trace_switch

#UCP Trace 记录点

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

#任务 Trace 记录点

#算子 Trace 记录点

#常用数据源介绍