qzl
179 lines
5.9 KiB
Markdown
179 lines
5.9 KiB
Markdown
# Apps 通用数据采集与报错日志系统设计（一阶段）
|
||
|
||
## 1. 背景与目标
|
||
|
||
当前前端需要在应用分发后具备可观测性能力，以支持线上报错定位和关键行为分析。
|
||
|
||
一阶段目标聚焦于“最小可用且可扩展”的通用采集体系，覆盖：
|
||
|
||
- 报错日志收集与排查支持。
|
||
- 用户打开应用时间与会话持续时长。
|
||
- 页面停留时长。
|
||
- 对话输入耗时与发送次数。
|
||
|
||
本设计优先保证数据质量、隐私安全、稳定性与后续重构兼容性，不绑定当前目录结构和具体实现文件。
|
||
|
||
## 2. 设计范围
|
||
|
||
### 2.1 一阶段纳入
|
||
|
||
- 全局异常采集（框架异常、异步未捕获异常、业务显式上报异常）。
|
||
- 会话生命周期采集（开始、结束、时长）。
|
||
- 页面生命周期采集（进入、离开、停留时长）。
|
||
- 对话输入行为采集（输入开始、输入提交）。
|
||
|
||
### 2.2 一阶段不纳入
|
||
|
||
- 复杂埋点体系（曝光、点击流全量追踪、实验分流）。
|
||
- 全量性能指标体系（FPS、内存、卡顿详细分层）。
|
||
- 非关键业务域的大规模事件扩展。
|
||
|
||
## 3. 方案选型结论
|
||
|
||
采用“自研通用采集 SDK + 自有后端接收”的主路径。
|
||
|
||
原因：
|
||
|
||
- 关键数据字段需与业务强关联，需高可定制能力。
|
||
- 需要强约束隐私边界与脱敏策略。
|
||
- 一阶段目标明确且有限，自研成本可控。
|
||
- 后续可平滑扩展第三方崩溃平台作为补充，不影响主链路。
|
||
|
||
## 4. 总体架构
|
||
|
||
系统分为四层：
|
||
|
||
1. 采集层：负责统一接入错误、会话、页面、输入等事件源。
|
||
2. 处理层：负责事件标准化、上下文补全、脱敏、去重与采样。
|
||
3. 存储层：负责本地队列缓存、离线持久化、容量控制。
|
||
4. 上报层：负责批量传输、失败重试、退避与状态感知。
|
||
|
||
核心原则：
|
||
|
||
- 所有事件必须走统一入口。
|
||
- 业务代码不直接请求上报接口。
|
||
- 上报失败不能影响用户主流程。
|
||
|
||
## 5. 事件模型设计
|
||
|
||
### 5.1 事件分类
|
||
|
||
- error：异常与失败事件。
|
||
- lifecycle：应用/页面生命周期事件。
|
||
- behavior：关键操作行为事件。
|
||
|
||
### 5.2 一阶段标准事件
|
||
|
||
- app_session_started
|
||
- app_session_ended
|
||
- page_view_started
|
||
- page_view_ended
|
||
- chat_input_started
|
||
- chat_input_submitted
|
||
|
||
说明：
|
||
|
||
- 输入“次数”由 chat_input_submitted 聚合统计，不新增独立事件。
|
||
- 应用“持续事件”采用开始+结束计算时长，不使用固定频率心跳。
|
||
|
||
### 5.3 通用字段规范
|
||
|
||
每条事件统一包含：
|
||
|
||
- event_id：事件唯一标识。
|
||
- event_name：事件名。
|
||
- event_type：事件分类。
|
||
- event_time：客户端事件时间。
|
||
- session_id：会话标识。
|
||
- user_id_hash：用户标识哈希（可空）。
|
||
- app_version：应用版本。
|
||
- platform：平台类型。
|
||
- route：当前页面标识（可空）。
|
||
- payload：事件特有字段。
|
||
|
||
错误事件附加字段：
|
||
|
||
- error_type、error_message、stacktrace（按策略裁剪）。
|
||
- severity（warning/error/fatal）。
|
||
- fingerprint（聚合键）。
|
||
|
||
## 6. 关键指标口径
|
||
|
||
### 6.1 应用打开时间与会话时长
|
||
|
||
- 会话开始：应用进入可交互前台时记录。
|
||
- 会话结束：应用切到后台时记录。
|
||
- 时长计算：session_end_time - session_start_time。
|
||
- 异常中断补偿：若会话未正常结束，在下次启动时补偿结束记录，并标记为补偿事件。
|
||
|
||
### 6.2 页面停留时长
|
||
|
||
- 页面进入时记录 page_view_started。
|
||
- 页面离开时记录 page_view_ended 与 duration_ms。
|
||
- 页面切换由统一路由观察机制触发，确保口径一致。
|
||
|
||
### 6.3 对话输入时间与次数
|
||
|
||
- 用户首次进入输入状态时记录 chat_input_started。
|
||
- 用户提交输入时记录 chat_input_submitted。
|
||
- 输入时长：submit_time - input_start_time。
|
||
- 输入次数：按提交事件数量聚合。
|
||
- 不采集输入正文，仅采集长度与时长。
|
||
|
||
## 7. 隐私与安全设计
|
||
|
||
必须遵循最小采集原则与默认脱敏策略：
|
||
|
||
- 禁止采集或上报：token、密码、手机号、邮箱、聊天正文、敏感证件信息。
|
||
- 标识类字段统一哈希化或匿名化。
|
||
- 错误消息与堆栈按规则裁剪，避免包含敏感上下文。
|
||
- 采用字段白名单策略，非白名单字段默认不上报。
|
||
|
||
安全底线：
|
||
|
||
- 采集系统本身不可引入认证绕过与敏感信息泄露风险。
|
||
- 上报通道需具备鉴权与重放防护能力。
|
||
|
||
## 8. 稳定性与性能策略
|
||
|
||
- 事件写入本地队列后异步上报，主线程不阻塞。
|
||
- 批量上传，控制单次包体和频率。
|
||
- 失败使用指数退避重试，达到上限后丢弃并记录内部统计。
|
||
- 本地队列设置容量上限，采用环形覆盖或优先级淘汰策略。
|
||
- 在弱网/离线场景允许延迟上报，恢复后补发。
|
||
|
||
## 9. 质量保障与验证
|
||
|
||
一阶段验收重点：
|
||
|
||
- 正确性：六类标准事件均可稳定产出且字段完整。
|
||
- 一致性：同类事件口径一致，可跨版本对比。
|
||
- 安全性：敏感字段泄露检测通过。
|
||
- 稳定性：采集开启后不影响主要业务链路。
|
||
|
||
建议验证维度：
|
||
|
||
- 会话开始/结束与时长计算一致性。
|
||
- 页面进出成对率。
|
||
- 输入开始到提交链路闭环率。
|
||
- 错误事件聚合有效性（fingerprint 去重后可读）。
|
||
|
||
## 10. 演进路线
|
||
|
||
二阶段建议按需扩展：
|
||
|
||
- 增加更多关键业务事件（保留最小集合原则）。
|
||
- 引入崩溃平台作为补充通道（仅 fatal/crash）。
|
||
- 建立统一查询与告警规则（高频错误、关键路径失败率）。
|
||
- 增强版本对比分析能力，支持发布质量回归判断。
|
||
|
||
## 11. 决策摘要
|
||
|
||
一阶段采用通用采集体系，围绕“报错日志 + 三类关键行为”快速落地：
|
||
|
||
- 会话：打开与持续时长。
|
||
- 页面：停留时长。
|
||
- 对话：输入时长与提交次数。
|
||
|
||
在不依赖具体重构代码结构的前提下，该设计可作为后续大重构期间的稳定观测基线。
|