social-app/docs/plans/2026-03-26-apps-telemetry-design.md

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. 决策摘要

一阶段采用通用采集体系，围绕“报错日志 + 三类关键行为”快速落地：

• 会话：打开与持续时长。
• 页面：停留时长。
• 对话：输入时长与提交次数。

在不依赖具体重构代码结构的前提下，该设计可作为后续大重构期间的稳定观测基线。