第4章 日志上报触发机制：主动上报、被动上报、采样策略、重试与幂等处理

4.1 适用场景

本章适用于Crash治理团队在客户端SDK层设计日志上报链路时的决策与配置。当应用发生Crash或采集到异常事件后，需要确定何时、以何种方式将日志传输到服务端。主要场景包括：

• 主动上报：用户触发（如点击“反馈”）、关键业务节点完成时主动发起日志上传。
• 被动上报：应用启动时检测到上次Crash日志、系统定时唤醒、网络状态恢复后自动补传。
• 采样策略：海量用户场景下按比例、按用户ID、按设备ID等维度控制上报量，避免服务端压力。
• 重试与幂等处理：网络不稳定或服务端返回错误时，保证日志最终成功上报且不产生重复记录。

4.2 前置条件

4.3 操作步骤

1. 触发决策：Crash事件入库后，SDK根据事件类型（崩溃/ANR/自定义异常）判断是否立即触发主动上报。
2. 采样过滤：若当前事件通过采样黑/白名单检查且随机数在采样比例内，才允许进入上报队列；否则丢弃。
3. 队列入队：通过条件的事件进入本地持久化队列（SQLite或文件序列），标记状态为pending。
4. 网络检测与被动触发：若当前网络可用（WiFi优先），立即启动上报；否则等待网络恢复后自动触发被动上报。
5. 发起HTTP请求：使用POST方法将日志JSON包发送至服务端，请求头携带X-Request-Id（唯一幂等键）。
6. 处理响应：服务端返回200则标记状态为success；若返回409（重复）则也可视为成功；其他错误码（5xx/4xx）进入重试逻辑。
7. 重试策略：采用指数退避（初始1秒，最大64秒，最多3次）。每次重试前检查本地队列状态以避免重复。
8. 幂等清理：上报成功后根据X-Request-Id清除本地待上传文件；若10分钟后仍没有收到服务端确认，允许重新上报但携带相同幂等ID。

4.4 输入输出物

4.5 责任边界

• 客户端SDK组：实现上报逻辑、采样算法、重试机制、幂等去重；不得遗漏用户隐私数据。
• 服务端组：提供幂等校验接口（基于X-Request-Id）、返回准确的HTTP状态码、保证日志最终存储不丢不重。
• QA组：构造网络异常、并发上报、重复请求、采样率边界等场景进行验证。
• 运维组：监控上报流量，配置采样阈值告警。

4.6 记录材料

• 上报触发日志（客户端本地logcat）：

  [CrashSDK][2025-02-20 10:00:01] Trigger: active, eventId=abc123
  [CrashSDK][2025-02-20 10:00:02] Sampling: pass (ratio=0.1, rand=0.05)
  [CrashSDK][2025-02-20 10:00:03] Queued: status=pending
  [CrashSDK][2025-02-20 10:00:04] HTTP POST: url=https://api.example.com/v1/crash, X-Request-Id=uuid-xxx
  [CrashSDK][2025-02-20 10:00:05] Response: 200 OK, removed local

• 服务端幂等日志：记录每个X-Request-Id首次到达时间及重复请求被拒绝次数。

4.7 异常处理

4.8 验收标准

• ✅ 主动上报：用户在WiFi下点击反馈，日志在5秒内到达服务端。
• ✅ 被动上报：模拟飞机模式开启→写入Crash→关闭飞机模式，日志在60秒内补传完成。
• ✅ 采样策略：配置采样率0.01，在10000次模拟Crash中，服务端接收量在80~120之间。
• ✅ 重试与幂等：服务端故意返回500两次，第三次返回200，客户端仅发送3次请求且最终成功；同一X-Request-Id被重复发送时服务端返回409，客户端不删除本地文件。
• ✅ 并发安全：同时写入10个Crash日志，上报时无乱序、无重复、状态文件一致。

fun retryWithExponentialBackoff(request: Request, maxRetries: Int = 3) {
    var delay = 1000L
    for (i in 1..maxRetries) {
        val response = httpClient.execute(request)
        if (response.isSuccessful || response.code == 409) return
        Thread.sleep(delay)
        delay = minOf(delay * 2, 64000L)
    }
    logError("Max retries exceeded for request ${request.id}")
}