4. Trace 文件导出与完整性验证

Trace 文件是卡顿分析的唯一原始证据。导出阶段如果出现截断、损坏或丢失关键段，后续所有分析都将失去依据。本章提供一套“导出时即完成验证”的实战规则，避免将损坏的 Trace 带入下个环节。

4.1 现象识别：导出失败或文件异常

在导出阶段常见的异常现象分为以下四种：

4.2 数据采集：标准导出命令与参数

确保使用以下导出命令，避免通过 adb pull 手动搬运未完成的文件：

# 标准导出到本地文件，自动等待录制完成并写入完整 header
adb shell perfetto --out /data/local/tmp/trace.perfetto-trace \
  -c /data/local/tmp/config.pbtx \
  --txt

# 导出完成后从设备拉取到本地
adb pull /data/local/tmp/trace.perfetto-trace ./trace.perfetto-trace

关键参数解释：

4.3 原因定位：文件大小判断与截断异常处理

根据文件大小快速定位问题：

截断异常的快速判断方法：

# 使用 perfetto 自带的验证命令
perfetto --query /path/to/trace.perfetto-trace

# 输出包含以下行表示完整：
# trace_size: 21894106 bytes
# packet_count: 145213
# has_finished: true

# 输出包含以下行表示截断：
# has_finished: false
# truncated_at: 1678901234567890123

4.4 修复动作：重录判断条件与自动化流程

以下任意条件满足时，必须启动重录流程：

1. 文件大小为 0 或 < 2KB
2. perfetto --query 显示 has_finished: false
3. 在 UI 中打开时提示“Trace Truncated”
4. 文件大小 < 配置中 buffer_size_kb 的 60%（说明数据严重缺失）

重录动作标准化操作：

# 删除残留的临时文件
adb shell rm -f /data/local/tmp/trace.perfetto-trace

# 检查设备可用存储
adb shell df -h /data/local/tmp

# 重新推送配置并启动录制
adb push config.pbtx /data/local/tmp/config.pbtx
adb shell perfetto --out /data/local/tmp/trace.perfetto-trace \
  -c /data/local/tmp/config.pbtx --txt

4.5 复测：导出后立即验证

每次导出后执行以下三步验证，确认文件可用性：

• 步骤1： 检查物理文件大小，记录到日志
• 步骤2： 运行 perfetto --query 确认完整性
• 步骤3： 在 Perfetto UI 中打开前 3 秒，确认时间轴和进程列表完整

复测通过后，将文件重命名为 trace_${场景名}_${日期}_checkok.perfetto-trace，防止后续混淆。

4.6 预防：导出行为的标准化规范

4.7 故障树：导出完整性排查

故障树总结了导出阶段最关键的三个研判节点。记住：文件不完整，分析不开始。养成导出后立即执行 perfetto --query 的肌肉记忆，才能确保后续卡顿定位有可靠的原始数据作为基础。

4.8 排查速查表