hm-trace-report

把已解析的 hitrace 与 hiperf 数据导出为一份可离线打开的交互报告：trace_report.html。

报告是自包含 HTML（内嵌数据与前端脚本），用浏览器直接打开 file:// 路径即可，无需本地服务。

你能得到什么

| 能力 | 说明 | |------|------| | Hitrace 主表 | 虚拟滚动浏览大量事件；按 tid / 任务 / 事件 / 栈状态筛选；内容关键词跳转 | | 调用栈侧栏 | 点击有符号栈的行，查看匹配的 hiperf callchain（含应用源码帧优先展示） | | 风险 Tab | 可选：注入与 dump_stack 同源的风险结论；有数据时排在首位并默认选中，可跳转匹配的 Hitrace 行 / FFRT gid | | FFRT Tab | 可选：按 gid 聚合生命周期、伴生事件（文件访问 / 失效触发）、Exec 片段摘要 | | 逐步丰富 | 先写基础 Hitrace，再附加 FFRT / 风险并覆盖同一 HTML | | 离线可用 | 单文件导出，拷贝到任意机器用浏览器打开 |

安装

npm install hm-trace-report

需要 Node.js ≥ 18。本包为 ESM。

你通常还需要：

• hmtrace-parser — 解析 hitrace、构建索引、可选 FFRT 聚合
• hiperf_txt_parser — 解析 / 解码 perf 文本得到 PerfData

快速开始

典型流程：组装载荷 → 写出 HTML。

import {
  buildTraceHtmlPayload,
  exportTraceReportHtml,
} from "hm-trace-report";
import {
  parseHitraceText,
  buildHitraceIndexSnapshot,
  // 可选：aggregateFfrtByGid 等 FFRT API（以 hmtrace-parser 文档为准）
} from "hmtrace-parser";
import type { PerfData } from "hiperf_txt_parser";

// 1. 准备 hitrace 展示数据与线程索引
const displayData = parseHitraceText(hitraceText);
const index = buildHitraceIndexSnapshot(displayData);

// 2. 组装报告载荷（仅 Hitrace Tab 时 ffrtEnabled: false）
const payload = buildTraceHtmlPayload({
  displayData,
  index,
  ffrtEnabled: false,
});

// 3. 写出自包含 HTML（perfData 用于预计算匹配与内嵌 callchain）
const perfData: PerfData = /* 你的解码结果 */;
await exportTraceReportHtml("./out/trace_report.html", payload, perfData);

然后在浏览器中打开 ./out/trace_report.html。

逐步丰富（推荐）

分析流水线可先导出基础 Hitrace，再在 FFRT / dump_stack 就绪后附加并覆盖同一文件：

import {
  buildTraceHtmlPayload,
  attachFfrtAggregatesToTraceHtmlPayload,
  exportTraceReportHtml,
  type TraceHtmlRiskFindingView,
} from "hm-trace-report";

// ① 基础 Hitrace
let payload = buildTraceHtmlPayload({
  displayData,
  index,
  ffrtEnabled: false,
});
await exportTraceReportHtml(htmlPath, payload, perfData);

// ② 附加 FFRT（注册 lifecycle / 伴生记录，并启用 FFRT Tab）
payload = attachFfrtAggregatesToTraceHtmlPayload(payload, ffrtAggregates);
await exportTraceReportHtml(htmlPath, payload, perfData);

// ③ 附加风险 Tab（与 dump_stack 同源条目；导出时自动尝试匹配 hiperf / hitrace / FFRT）
const riskFindings: TraceHtmlRiskFindingView[] = /* 由调用方从 dump_stack PerfData 构建 */;
payload = { ...payload, riskFindings };
await exportTraceReportHtml(htmlPath, payload, perfData);

在 snapshot-checker 中，上述步骤由 trace_html_pipeline 封装（exportTraceHtml / enrichTraceHtmlWithFfrtAndExport 等），可随时覆盖写出。

一次性启用 FFRT Tab

也可在首次组装时直接传入：

const payload = buildTraceHtmlPayload({
  displayData,
  index,
  ffrtEnabled: true,
  ffrtAggregates: aggregates, // FfrtGidAggregate[]
});

await exportTraceReportHtml("./out/trace_report.html", payload, perfData);

报告中会出现 FFRT Tab：左侧按 gid 列表（带伴生事件标签的项优先），右侧展示任务发起、子任务与可折叠的生命周期表。

启用风险 Tab

在 payload 上设置 riskFindings（undefined 不展示 Tab；[] 表示已分析但无风险项）。导出时库会尝试为每条风险填充：

• hiperfSampleIndex — 匹配的内嵌 hiperf 样本
• hitraceRecordIds — 可供「在 Hitrace 中查看」的记录
• ffrtGids — 可供「在 FFRT 中查看」的 gid

匹配失败时仍展示 dump_stack 结论，仅无跳转按钮。

报告怎么用（浏览器端）

1. 用 Chrome / Edge 等打开生成的 HTML（file:// 即可）。
2. 风险（若注入）：位于 Tab 栏首位并默认打开，查看与 dump_stack 一致的失效结论；详情中可跳到 Hitrace / FFRT。
3. Hitrace：在查询栏用 label 芯片筛选，或用内容检索配合 ↑↓ 跳转；有符号栈的行可点开右侧「调用栈信息」。
4. FFRT（若启用）：选中 gid 查看生命周期状态、Exec 摘要与伴生事件；可用 gid / 内容检索缩小范围。

栈列短标签含义：

| 列表显示 | 含义 | |----------|------| | 无符号 | 有 hiperf 匹配但无可展示符号栈；行不可点 | | 有符号 | 有符号栈，但不含 .ts / .ets / .js | | 应用栈 | 符号栈含 .ts / .ets / .js 源码帧 | | — | 无 hiperf 匹配 |

API（调用方常用）

buildTraceHtmlPayload(input)

由 hitrace 数据生成嵌入报告的载荷。

| 字段 | 类型 | 说明 | |------|------|------| | displayData | HitraceData | 主表要展示的 hitrace 记录 | | index | HitraceThreadIndexSnapshot | 线程索引，用于与 hiperf 反向关联 | | ffrtEnabled | boolean | 是否启用 FFRT Tab | | ffrtAggregates | FfrtGidAggregate[]（可选） | FFRT 聚合结果；仅在 ffrtEnabled 时使用 |

未传 FFRT 时得到基础 Hitrace 载荷（ffrtEnabled: false），可稍后用 attachFfrtAggregatesToTraceHtmlPayload 附加。

attachFfrtAggregatesToTraceHtmlPayload(payload, ffrtAggregates)

在已有基础 Hitrace payload 上注册 FFRT lifecycle / 伴生记录，设置 ffrtEnabled: true 与 ffrtAggregates 视图。返回新 payload，不写盘。

exportTraceReportHtml(outputPath, payload, perfData)

将载荷与 PerfData 写成自包含 HTML：

• 预计算 hitrace ↔ hiperf 匹配
• 若存在 riskFindings，尝试关联 hiperf / hitrace / FFRT 链接字段
• 仅内嵌被引用的样本与 callchain，控制体积
• 写入原子替换的目标文件

成功后即可用浏览器打开 outputPath。可反复调用以覆盖同一文件（逐步丰富）。

风险相关

| 导出 | 说明 | |------|------| | TraceHtmlRiskFindingView / TraceHtmlRiskKind | 风险条目类型 | | shouldShowRiskTab(payload) | 是否应渲染风险 Tab | | enrichRiskFindingsLinks 等 | 导出流程内部也会调用；需要自定义匹配时可直接使用 |

错误与预算

导出前会校验记录数、样本数与序列化体积。超限抛出 BudgetExceededError（code: "BUDGET_EXCEEDED"，exitCode: 2）。

可用环境变量调大上限（仍受绝对上限约束）：

| 变量 | 作用 | |------|------| | TRACE_HTML_MAX_RECORDS / ANALYSIS_MAX_RECORDS | 最大记录数 | | ANALYSIS_MAX_SAMPLES | 最大 hiperf 样本数 | | TRACE_HTML_MAX_BYTES / ANALYSIS_MAX_SERIALIZED_BYTES | 最大输出字节 | | TRACE_HTML_MAX_CALLCHAIN_FRAMES / ANALYSIS_MAX_CALLCHAIN_FRAMES | 单条 callchain 最大帧数 |

也可用 isBudgetExceededError(err) 识别该类错误。

与 snapshot-checker 的关系

若你使用 snapshot-checker 的 report / analysis 流程，工具会在满足条件时自动生成同款 trace_report.html（基础 Hitrace → 可选 FFRT → dump_stack 同源风险，逐步覆盖）。本库适合你已有解析结果、希望单独导出报告或嵌入自有流水线的场景。

许可

MIT