docs: add startup monitoring integration plan

2026-08-05 14:06:55 +08:00
parent 2134f54010
commit f947f3d2f8
1 changed files with 50 additions and 0 deletions
@@ -0,0 +1,50 @@
+# HarmonyOS 启动性能监控接入方案
+
+## 1. 目标
+
+建立冷启动耗时的线上采集、聚合和看板能力，用于发现版本或分支引入的启动性能劣化。统计口径以“用户点击图标”至“首页首帧完成”为准，单位为毫秒。
+
+## 2. 总体链路
+
+`APP_LAUNCH` 系统事件提供启动类型和系统耗时；首页完成首次有效绘制后，通过 `reportDrawnCompleted` 标记首帧终点。客户端将两者组合为自定义启动指标，由 APM SDK 本地采样、聚合后上传；后台按模块配置阈值和采样策略，并在 ELK/Grafana 展示趋势与分位数。
+
+## 3. 客户端接入
+
+在 `future_entry_demo/src/main/ets/monitor/APMHelper.ets` 中初始化与现有 `HXMonitor` 同体系的 HarmonyOS 自定义 APM 事件能力；不要直接复用 Android 文档中的 Java API。
+
+在 `EntryAbility.ets` 中订阅 `APP_LAUNCH`，读取：
+
+- `start_type`：启动类型；仅 `0` 纳入冷启动统计。
+- `extend_time`：从抬手到应用报告首帧完成的耗时。
+- `animation_finish_time`、`icon_input_time`、`bundle_version`：用于分析和问题追溯。
+
+在首页根节点完成第一次有效绘制时仅上报一次 `reportDrawnCompleted`。隐私页、网络异常页等可能成为首次可见页面的入口也应覆盖，否则对应场景的首帧时间会失真。
+
+## 4. 指标定义
+
+| 项目 | 建议值 |
+|---|---|
+| 模块 | `launch` |
+| 指标名 | `cold_start_time` |
+| 指标值 | 冷启动耗时，单位 ms |
+| 维度 | `start_type`、`entry_page`、`app_version` |
+| 分桶 | `[500, 800, 1200, 2000, 3000]` |
+
+模块名使用小写字母和连字符；指标名不包含连字符。维度控制在必要范围内，避免将用户 ID、完整 URL 等高基数字段作为维度。
+
+## 5. 后台与看板配置
+
+按新增 PDF 的自定义 APM 模块流程，在 APM 后台创建 `launch` 模块并启用：全量采样（`sampling_rate: 1000`）、60 秒聚合（`aggre_time: 60`）、累计 100 条触发上报（`aggre_count: 100`）。随后为该模块补充 ELK 索引模板，在 Grafana 建立按版本、启动类型和时间聚合的 P50/P95、超 2 秒占比及分桶分布面板。
+
+## 6. 兼容与兜底
+
+现有 `AppEvent.ets` 的 `ElkService` 可以上传结构化启动日志，但它不具备 PDF 所述的指标聚合语义。优先确认 HarmonyOS 是否提供与 Android 自定义 APM SDK 对应的包和 API；若暂未提供，则先通过 `ElkService` 上传 `cold_start_time`、维度和原始系统字段，并由后端补充索引、聚合规则和看板。
+
+`APP_LAUNCH` 的事件解析必须与崩溃事件分开处理：崩溃事件依赖异常和日志字段，启动事件不包含这些字段。上传应异步执行，不阻塞首页渲染；以 `time + icon_input_time + start_type + process_name` 去重，兼容系统重新投递。
+
+## 7. 验收标准
+
+1. 每次冷启动只产生一条可查询记录，且 `extend_time` 大于 0。
+2. 本地日志/性能工具的耗时与后台数据量级一致。
+3. 看板可按版本和冷启动维度查询 P50、P95、超阈值占比及分桶分布。
+4. 断网、重复回调或上传失败不影响启动流程，网络恢复后按既有上传机制重试。