harmony-crash-analysis-report/apm_launch_monitor_config.md

启动性能监控（冷启动耗时）接入配置

作者：cheliangzhao 日期：2026-08-06 涉及模块：entry（HAP 入口）+ @kernel/app_monitor_event（APM 事件 SDK） 对应需求：冷启动耗时（cold_start_time）采集与看板聚合

---

1. 背景与目标

统计同花顺期货鸿蒙版冷启动耗时，覆盖三条启动入口（Index / LauncherPage / NetworkAnomalyPage），区分冷启动 / 补投递四种场景，实现启动性能的持续观测与劣化告警。

采集分两条通道：

• 链路 A（Elk 追溯，已上线验证）：把冷启动指标结构化 JSON 经 ElkService 异步上报，字段最全，可明细定位。
• 链路 B（HXEventMonitor 分桶，需后台策略开启后生效）：由 SDK 按桶自动归集，负责看板聚合曲线。

⚠️ 链路 B 是策略驱动的：SDK 侧在 EventMonitorStrategy 找不到 launch 模块的开启策略时，create()/record() 一律空转并打印 Monitor.Event cold_start_time eventId has not created!。应用侧无法绕开，必须由 APM 后台下发对应模块策略才能激活。

---

2. 链路 A：Elk 追溯（已生效，无需后台操作）

上报字段（LaunchElkBuilder，业务来源 launch）：

字段	类型	说明
cold_start_time	number	冷启动耗时 ms = 系统事件 extend_time
start_type	number	启动类型（当前只统计 0=冷启动）
entry_page	string	入口页（Index/LauncherPage/NetworkAnomalyPage；补投递为 unknown）
app_version	string	应用内部版本号
app_install_status	string	normal/new_install/over_written
response_latency	number	离手到动效开始（需 API 22+）
animation_finish_time	number	动效完成耗时
startability_processstart_dur	number	进程创建段（仅冷启动）
appattach_to_appforeground_dur	number	进程挂载段（仅冷启动）
git_commit	string	代码级追溯，劣化定位用
is_backfill	boolean	是否系统补投递的上次启动遗留事件

---

3. 链路 B：HXEventMonitor 分桶指标（需后台开启）

3.1 后台需下发的模块策略

SDK 由 HXEventMonitorPlugin.parseMonitorStrategy() 读取，注入到 EventStrategyBean 后按模块打开。请为 module=launch 下发如下配置：

{
  "module": "launch",
  "config": {
    "status": 1,
    "sampling_rate": 1.0,
    "interval": 5000,
    "aggre_time": 60000,
    "aggre_count": 10
  }
}

字段说明（对齐 EventStrategyBean.fromJson，仅这些字段生效）：

字段	取值	说明
module	launch	必须与代码 HXEventMonitor.getEventFactory('launch') 一致
status	1	必须 1（STATUS_OPEN）；否则 isOpen() 为 false，create/record 全空转
sampling_rate	0~1	抽样率，isOpen() 需 status==1 && 抽样通过 才生效
interval	ms	采集间隔
aggre_time	ms	聚合时间阈值，达到即触发一次 push
aggre_count	条	聚合数量阈值，达到即触发一次 push

3.2 指标定义

项	值
模块名 module	launch
指标名 metric	cold_start_time
值域	冷启动耗时 ms（extend_time）
分桶 buckets	[500, 600, 700, 800, 1000, 1500, 2000, 3000]（按实测 600–800ms 主体细分，尾部留劣化锚点）
维度1 start_type	冷启动 0
维度2 entry_page	Index/LauncherPage/NetworkAnomalyPage/unknown(补投递)
维度3 app_version	应用内部版本号
维度4 app_install_status	normal/new_install/over_written

3.3 判定生效

后台下发后，重启应用，冷启动日志中：

• ✅ 消失：Monitor.Event cold_start_time eventId has not created!
• ✅ 出现：Cold start bucket metric recorded: <ms> 与 SDK 聚合 push 日志
• ✅ 看板出现 launch 模块 cold_start_time 桶分布

---

4. 相关代码与文件

文件	作用
entry/src/main/ets/monitor/LaunchMonitor.ets	APP_LAUNCH 订阅、Elk 上报、首帧 reportDrawnCompleted、桶指标定义与 record
entry/src/main/ets/monitor/LaunchMonitor.ets（ensureColdStartMetric）	创建 launch/cold_start_time 桶指标（幂等）
entry/src/main/ets/monitor/plugin/HXLaunchMonitorPlugin.ets	仿 HXCrashMonitorPlugin 接入的启动插件，在 startPlugin() 建指标
entry/src/main/ets/monitor/APMHelper.ets	注册 HXLaunchMonitorPlugin 及配置类、.plugin(...) 列表
entry/src/main/ets/entryability/EntryAbility.ets	onCreate 早注册 LaunchMonitor.init()
entry/src/main/ets/pages/Index.ets / LauncherPage.ets / network/NetworkAnomalyPage.ets	首帧 HOME_ROOT 监听 + reportFirstFrameOnDraw/dispose

打点时序

EntryAbility.onCreate → LaunchMonitor.init()（注册 APP_LAUNCH watcher）
入口页 aboutToAppear → reportFirstFrameOnDraw(HOME_ROOT) → 首帧 draw → reportDrawnCompleted()
系统产生 APP_LAUNCH 事件（冷启动）→ onReceive
  ├─ 链路A: ElkService 上传冷启动 JSON（字段见 §2）
  └─ 链路B: HXEventMonitor record(cold_start_time)（依赖 launch 策略，见 §3）
补投递：icon_input_time 早于 watcher 注册 > 2000ms → 判为 backfill，entry_page=unknown

---

5. 真机验证结论（2026-08-06，nova 14 Pro）

场景	结果
全新安装首启（new_install）	链路 A：cold_start_time=1141ms，Entry=Index，Elk 上报 ✅
二次冷启动（normal）	链路 A：cold_start_time=1717ms，Elk 上报 ✅
链路 B（分桶）	❌ 待后台下发 launch 策略（§3.1）后复测

编译：./claude_tool/claude_compile.sh → BUILD_SUCCESS