日志回捞
功能概述
日志回捞功能为研发团队提供按需远程获取客户端日志的能力，帮助快速定位和解决线上疑难问题。区别于传统的全量日志上传方案，日志回捞将客户端日志保存在本地，仅在需要时通过任务方式拉取指定用户的日志，大幅降低存储成本，提升日志利用率。
与传统方案对比
传统全量日志方案的问题
- 所有用户日志全部上传到平台
- 日志利用率极低（仅 5% 的数据被使用）
- 95% 的数据从未被查看，造成严重的存储资源浪费
- 持续消耗带宽和存储成本
- 海量日志查询性能差
日志回捞方案的优势
- 客户端日志保存在本地，不主动上传
- 仅在需要时拉取指定用户的日志
- 日志利用率接近 100%（按需拉取）
- 大幅降低存储成本和带宽消耗
- 查询性能高，精准定位问题
核心价值
- 按需获取：仅拉取需要分析的用户日志，日志利用率接近 100%
- 成本优化：避免全量上传，节省 95% 以上的存储和带宽成本
- 问题快速定位：获取完整的客户端日志，快速还原问题现场
- 批量排查支持：支持同时拉取多个用户的日志，批量分析问题
- 隐私安全可控：按需拉取、过期自动取消，保护用户隐私
什么是日志回捞
日志回捞是一种远程获取客户端本地日志 的技术手段。当线上出现疑难问题通过基础数据无法分析时，通过创建日志回捞任务，SDK 会将指定用户设备上本地存储的日志数据上传到平台，供研发团队进行深度分析。
工作流程
1. 客户端本地保存日志（7天）
↓
2. 研发创建回捞任务（指定用户/设备、时间范围）
↓
3. SDK 接收任务指令（用户设备在线时）
↓
4. 满足条件时上传日志（WiFi/移动网络）
↓
5. 平台展示日志
技术要求
- SDK 版本：需开启「日志回捞」模块开关
- 本地存储：SDK 以天粒度生成日志文件，单文件最大 10MB（可配置）
- 存储容量：本地最多存储 7 份日志文件，约 70MB
- 网络要求：需要用户设备在线且满足网络条件
重要限制
SDK 初始化要求
- 客户端必须完成 SDK 初始化后才能接收日志回捞任务
- 未初始化或初始化失败的设备无法收到回捞指令
- 仅在 SDK 正常工作的情况下才会上传本地日志文件
采样限制
- 如果客户端被采样（未在监控范围内），则不会收集日志数据
- 被采样的设备即使创建回捞任务也无法获取日志
注意：创建任务前，建议先确认目标设备是否在监控范围内（未被采样）且 SDK 已正常初始化。
使用场景
场景一：崩溃问题深度排查
崩溃堆栈信息不足以定位问题，需要更多上下文日志。
实践案例：
- 用户反馈特定操作后应用崩溃
- 崩溃堆栈显示在第三方 SDK 中发生，但原因不明
- 通过用户 ID 创建日志回捞任务
- 回捞日志发现崩溃前有网络请求异常
- 定位到是接口返回数据格式异常导致
- 修复后崩溃率下降 85%
场景二：卡顿问题根因分析
卡顿监控发现问题，但需要详细的操作日志定位根因。
实践案例：
- 某用户频繁遇到页面卡顿
- 卡顿分析显示主线程阻塞，但无法定位具体原因
- 回捞该用户 7 天的日志
- 日志显示每次卡顿前都有大量图片加载操作
- 优化图片加载策略，问题解决
场景三：批量用户问题排查
多个用户报告相同问题，需要批量获取日志分析共性。
实践案例：
- 特定版本有 50 个用户报告支付失败
- 创建回捞任务，批量拉取 50 个用户日志
- 日志分析发现都在调用支付 SDK 时失败
- 定位到是新版本支付 SDK 初始化参数错误
- 紧急热修复，问题快速解决
核心功能
1. 任务列表
访问路径：顶部导航菜单 → 日志回捞
任务列表展示所有日志回捞任务的状态和进度。
列表字段
| 字段 | 说明 | 状态值 |
|---|---|---|
| 任务名称 | 创建任务时填写的名称 | - |
| 创建人 | 当前登录的账号名称 | - |
| 任务进度 | 当前任务的状态 | 已完成、进行中、已取消 |
任务状态说明
| 状态 | 判断条件 | 说明 |
|---|---|---|
| 已完成 | 成功捞取日志的设备数 = 配置的设备数 | 所有设备日志已成功回捞 |
| 进行中 | 成功捞取日志的设备数 < 配置的设备数 | 等待设备上线或满足上传条件 |
| 已取消 | 主动点击取消 或 到达过期时间 | 任务已终止，不再拉取数据 |
说明：任务支持配置多个设备，系统会记录配置的设备个数和已成功捞取日志的设备个数。
操作功能
- 查看详情：查看任务配置和日志收集情况
- 编辑：修改任务配置（仅进行中的任务）
- 复制：基于现有任务快速创建新任务
- 取消：停止任务执行
- 删除：删除任务记录
2. 新建任务
任务配置参数
任务名称（必填）
- 说明：任务的标识名称
- 建议：使用有意义的名称，如"崩溃问题-用户A"、"卡顿排查-版本3.5.0"
- 注意：多个任务名称可重复
过期时间（必填）
- 说明：任务自动取消的时间
- 作用：到达过期时间后任务自动取消，不再拉取客户端数据
- 建议：
- 紧急问题：设置 1-3 天
- 一般问题：设置 7 天
- 长期监控：设置 15-30 天
拉取范围（必填）
- 说明：需要拉取日志的时间范围
- 作用：指定回捞哪个时间段的日志文件
- 示例：崩溃发生在 2025年10月5日，为保证数据完整性，可配置拉取 10月1日~10月10日 的日志
- 建议：
- 问题发生时间前后各扩展 2-3 天
- 避免范围过大影响上传效率
- 考虑日志本地最多保存 7 天的限制
上传时机（必填）
- 说明：客户端上传日志的网络条件
- 选项：
- WiFi 网络（推荐）：仅在 WiFi 下上传，节省用户流量
- 移动网络：仅在移动网络下上传
- 移动网络和 WiFi 网 络：任意网络均可上传，快速获取日志
- 建议：
- 紧急问题：选择"移动网络和 WiFi"
- 一般问题：选择"WiFi 网络"
选择设备（必填）
- 说明：需要捞取日志的设备标识
- 支持方式：
- 用户 ID：需要在 SDK 中配置
- 设备 ID：SDK 自动生成的设备唯一标识
- 输入方式：
- 单个 ID：直接输入
- 多个 ID：通过回车键分隔
- 批量导入：支持批量上传 ID 列表
- 限制：每个任务最多支持 100 个 ID
通知方式（选填）
- 说明：任务完成后的通知方式
- 作用：日志拉取成功后通过邮件通知
- 建议：建议填写，避免遗漏任务完成通知
任务说明（选填）
- 说明：任务的备注信息
- 作用：记录任务背景、问题描述、相关人员等
- 建议：详细记录便于后续追溯和协作
3. 任务详情
配置信息
展示任务创建 时的所有配置参数：
- 任务名称、过期时间、拉取范围
- 上传时机、选择设备、通知方式
- 任务说明
用途：
- 确认任务配置是否正确
- 了解任务的背景和目的
- 便于团队协作和问题追溯
日志收集列表
展示成功上传日志的设备信息：
列表字段
- 用户 ID / 设备 ID
- 日志上传时间
- 日志文件大小
- 日志时间范围
功能特性
- 检索：支持根据用户 ID 或设备 ID 快速检索
- 详情：点击【详情】按钮查看日志内容
- 导出：支持导出日志文件
状态说明
- 列表中的设备：已成功回捞日志
- 未出现的设备可能原因：
- 用户未上线
- 未满足上传时机（如等待 WiFi）
- 本地日志已过期删除
- SDK 未初始化或初始化失败
- 设备被采样，不收集日志
4. 日志详情
日志详情页面提供日志查看、过滤和分析功能。
日志展示
- 默认展示：1 万行日志
- 时间顺序：按时间倒序排列，最新日志在上
- 完整信息：包含时间戳、日志级别、标签、日志内容
过滤功能
时间过滤
- 默认范围：任务配置的拉取时间范围
- 自定义：可缩小时间范围精准定位
- 用途：快速定位问题发生时间段的日志
级别过滤
- 日志级别：Debug、Info、Warn、Error
- 默认：展示所有级别
- 用途：
- Error：快速查看错误日志
- Warn：查看警告信息
- Debug：查看详细调试信息
标签过滤
- 说明：日志携带的 Tag 信息
- 输入要求：需输入完整内容，区分大小写
- 用途：按功能模块、业务场景过滤日志
内容搜索
- 说明：搜索日志详情中的内容
- 支持：模糊匹配
- 用途：快速查找关键字、错误信息、特定方法
分析技巧
1. 快速定位错误
步骤：
1. 过滤 Error 级别日志
2. 查看错误发生时间
3. 向前查看 5-10 分钟的日志
4. 分析错误发生的上下文
2. 分析异常模式
步骤：
1. 搜索关键错误信息
2. 查看错误出 现的频率
3. 分析错误的共同特征
4. 定位问题的根因
日志本地存储机制
存储策略
文件生成
- SDK 以天为粒度生成日志文件
- 每天生成一个日志文件
文件大小
- 单个日志文件最大 10MB（可配置）
- 超过大小自动滚动创建新文件
- 可根据应用日志量调整大小
存储数量
- 本地最多存储 7 份日志文件
- 总大小约 70MB
- 超过数量自动删除最旧的文件
存储位置
- Android：应用私有目录
- iOS：应用沙盒目录
- Harmony：应用数据目录
重要：日志仅保存 7 天，超过 7 天的日志无法回捞。
最佳实践
1. 任务创建策略
按问题类型
| 问题类型 | 拉取范围 | 上传时机 | 设备数量 |
|---|---|---|---|
| 紧急崩溃 | 问题发生前后 1-2 天 | 移动网络+WiFi | 3-5 个典型用户 |
| 性能问题 | 问题发生前后 3-5 天 | WiFi | 10-20 个用户 |
| 功能异常 | 问题发生前后 2-3 天 | WiFi | 5-10 个用户 |
| 长期监控 | 近 7 天 | WiFi | 1-2 个用户 |
命名规范
建议使用结构化命名：
[问题类型]-[版本]-[简要描述]-[日期]
示例：
- 崩溃-v3.5.0-支付页面-20251010
- 卡顿-v3.4.5-首页加载-20251008
- 错误-v3.5.1-网络请求-20251012
2. 设备选择技巧
优先选择原则
-
高频问题用户
- 多次遇到问题的用户
- 日志更完整，问题更典型
-
典型环境用户
- 主流设备型号
- 主流系统版本
- 代表性强
-
问题明确用户
- 问题描述清晰
- 问题发生时间明确
- 便于定位
-
确认设备状态
- 设备未被采样（在监控范围内）
- SDK 已正常初始化
- 设备近期有活跃
获取设备 ID 方式
| 来源 | 路径 | 说明 |
|---|---|---|
| 崩溃详情 | 异常分析 → 崩溃详情 → 设备详情 | 直接从异常详情获取 |
| 卡顿详情 | 异常分析 → 卡顿详情 → 设备详情 | 直接从异常详情获取 |
| 用户追踪 | 用户追踪 → 搜索用户 → 用户详情 | 从用户轨迹中获取 |
| 会话详情 | 任意模块 → 单样本详情 → 会话 ID → 会话详情 | 从会话中获取 |
3. 日志分析方法
时间线分析法
-
定位问题时间点
- 根据崩溃、卡顿发生时间
- 精确到秒级
-
向前追溯
- 查看问题前 5-10 分钟日志
- 了解用户操作路径
- 发现异常前兆
-
向后查看
- 查看问题后的日志
- 了解应用恢复情况
- 分析影响范围
关键字搜索法
-
错误关键字
- Exception、Error、Crash
- Failed、Timeout、Null
-
业务关键字
- 支付、订单、登录
- 特定功能模块名称
-
技术关键字
- API 调用
- 数据库操作
- 第三方 SDK
级别过滤法
-
Error 级别
- 查看所有错误日志
- 识别高频错误
- 分析错误模式
-
Warn 级别
- 查看警告信息
- 发现潜在问题
- 预防性优化
-
Info/Debug 级别
- 了解正常流程
- 对比异常流程
- 定位差异点
5. 隐私保护
- 建议不要写入用户隐私数据到日志文件
- 任务过期自动取消
常见问题 FAQ
Q1：设备一直未上传日志怎么办？
A：可能的原因和解决方法：
1. 用户未上线
- 现象：设备离线，未打开应用
- 解决：等待用户上线，或联系用户打开应用
2. 网络条件不满足
- 现象：配置了 WiFi 上传，但用户一直用移动网络
- 解决：修改任务，改为"移动网络和 WiFi"
3. 日志已过期
- 现象：拉取范围超过 7 天，本地日志已删除
- 解决：无法回捞，建议创建新任务监控后续日志
4. 应用版本过低
- 现象：SDK 版本不支持日志回捞
- 解决：升级 SDK 版本并开启日志回捞模块
5. 存储空间不足
- 现象：设备 存储空间不足，日志未生成
- 解决：引导用户清理空间或等待空间释放
6. SDK 未初始化
- 现象：SDK 初始化失败，无法接收回捞任务
- 解决：检查 SDK 配置，确保初始化成功
7. 设备被采样
- 现象：设备在采样范围外，不收集日志数据
- 解决：选择未被采样的设备，或调整采样策略
Q2：日志太多如何快速定位关键信息？
A：使用过滤和搜索组合：
快速定位步骤
-
先过滤级别
- 选择 Error 级别
- 快速查看所有错误
-
再搜索关键字
- 输入错误类型（如 NullPointerException）
- 输入功能模块名（如 PaymentModule）
-
然后缩小时间
- 定位到问题时间附近
- 查看前后日志上下文
-
最后关联分析
- 取消过滤，查看完整日志
- 了解完整的执行流程
常用搜索关键字
- 异常：Exception、Error、Crash、Failed
- 网络：Request、Response、Timeout、404、500
- 业务：Login、Pay、Order、Cart
- 性能：Slow、OOM、ANR、Lag
Q6：日志回捞是否影响用户体验？
A：影响极小，SDK 已做充分优化：
性能影响
- 日志写入异步进行，不阻塞主线程
- CPU 开销 < 0.5%
- 内存开销 < 2MB
流量影响
- 可配置仅 WiFi 下上传
- 日志经过压缩传输
- 单次上传 < 10MB（约 70MB 压缩后）
存储影响
- 本地最多 70MB
- 相对应用数据量很小
- 自动清理过期文件
用户感知
- 日志生成无感知
- WiFi 下上传无感知，并且上传数据会做压缩处理以便减少流量消耗
- 不影响应用性能
可控性
- 可远程关闭日志回捞开关
- 可调整日志级别和文件大小
- 可配置不记录敏感信息