Log Analysis Troubleshooting

日志分析与排查技能

一、使用场景（什么时候用）

• 软件线上故障排查：用户反馈功能异常、操作失败、系统卡顿/崩溃时，通过日志定位问题根源

• 批量异常排查：出现大量用户投诉同一问题（如操作失败、登录异常），需快速筛选相关日志，判断影响范围

• 问题复现验证：研发修复问题后，通过日志检索，验证异常是否消失、功能是否恢复正常

• 性能瓶颈排查：系统响应缓慢时，检索日志中的超时、耗时过长记录，定位性能瓶颈点

• 日志量超限处理：日志量过大（突破tokens限制），需对日志进行合并、筛选，提取核心有效信息

• 异常预警排查：发现系统报错率、异常率上升时，通过日志分析异常原因，提前规避大规模故障

• 进程状态排查：确认软件进程（如守护进程）是否被异常退出、停止或重启

二、排查方法论（标准排查流程）

核心原则：先宏观后微观，先全局后局部，先时间后内容。

2.1 六步排查法（必须遵循的标准流程）

┌─────────────────────────────────────────────────────────────────────────────┐
│  第一步：概览分析 → 第二步：时间校验 → 第三步：范围定位                           │
│      ↓                                                                       │
│  第四步：异常聚类 → 第五步：事件链重构 → 第六步：根因定位 & 结论输出              │
└─────────────────────────────────────────────────────────────────────────────┘

第一步：概览分析（Overview）

目的：快速了解日志的基本情况，评估分析策略

执行方式：

python3 tools/smart_log.py overview --file "/path/to/app.log"

关注要点：

• 📁 文件大小：判断是否需要压缩去重
• ⏰ 时间范围：确认日志覆盖的时间区间
• 📊 级别分布：ERROR/WARN 数量，判断问题严重程度
• 🔥 高频错误类型：快速识别主要问题

第二步：时间校验（Time Validation）

目的：确认用户描述的问题时间点是否在日志覆盖范围内

常见陷阱：

• ⚠️ 用户说"15:40 出问题"，但日志只到 15:36
• ⚠️ 日志时间戳格式多样，直接 grep 可能匹配错误

执行方式：

# 使用 validate 命令（推荐）
python3 tools/smart_log.py validate --file "/path/to/app.log" --time "15:40"

# 或用 smart_log.py tail 查看末尾（推荐，带行号+时间戳）
python3 tools/smart_log.py tail --file "/path/to/app.log" --lines 50
head -50 /path/to/app.log

关键判断：

• 如果目标时间不在日志范围内，需要获取其他日志文件
• 日志截止时间本身可能就是问题发生的时刻（如进程被终止导致日志停止）

第三步：范围定位（Scope Location）

目的：缩小排查范围，聚焦问题时间段

执行方式：

python3 tools/smart_log.py timeline --file "/path/to/app.log" --start "15:35" --end "15:40"

⚠️ 时间戳精确匹配注意事项：

不同日志的时间戳格式不同，需要根据实际格式构造正则：

第四步：异常聚类（Error Clustering）

目的：将大量错误日志聚类分析，识别主要问题

执行方式：

python3 tools/smart_log.py errors --file "/path/to/app.log" --start "15:35" --end "15:40" --top 20

分析技巧：

• 关注突然激增的错误类型
• 对比正常时段和异常时段的错误分布
• 注意错误之间的时序关系

第五步：事件链重构（Event Chain Reconstruction）

目的：通过上下文关联，还原问题发生的完整链路

执行方式：

# 推荐：使用 chain 命令
python3 tools/smart_log.py chain --file "/path/to/app.log" \
  --start "15:35" --end "15:40" \
  --events "start,stop,init,exit,connect,disconnect"

# 或使用 search 命令
python3 tools/smart_log.py search --file "/path/to/app.log" \
  --keyword "exit|stop|quit|shutdown|disconnect|terminate" \
  --start "15:35" --end "15:40" \
  --dedupe --context 3

第六步：根因定位 & 结论输出

目的：基于日志证据，定位根本原因，输出结构化结论

结论模板：

## 📊 日志分析结论

### ⚠️ 问题现象
- [描述用户反馈的问题现象]

### 🔴 关键发现
| 时间 | 事件 | 日志证据 |
|------|------|----------|
| 15:35:03 | xxx | 具体日志内容（行号） |

### 🔍 根因分析
- 直接原因：[具体描述]
- 根本原因：[深层原因]

### 💡 建议
1. [可执行的建议1]
2. [可执行的建议2]

2.2 智能关键词推导

根据用户问题语义推导搜索关键词：

三、核心能力

3.1 日志检索与筛选

• 根据指定时间段、关键词（报错提示、接口/操作ID、设备ID）主动检索日志，高效过滤无关信息
• 熟练处理常见日志格式（JSON/文本/XML/Windows日志），快速提取关键信息（操作状态、报错堆栈、参数）
• 使用允许的工具独立完成日志检索，无需用户额外指导
• ⚠️ 必须先确认时间戳格式，再构造精确的搜索正则

3.2 异常识别与根因分析

• 自动识别各类日志异常（操作中断、接口报错、超时、权限/配置错误、进程退出）
• 通过日志上下文关联重构问题链路，精准判断问题类型（网络、配置、接口、环境问题）
• 区分偶发/批量问题、环境/产品问题，基于日志证据定位根因，确保判断严谨
• ⚠️ 日志截止时间本身可能是重要线索（如进程被杀导致日志停止）

3.3 排查结果落地

• 将日志分析过程与结果转化为结构化结论，明确说明问题现象、日志证据及根因
• 针对简单问题提供可落地的解决方案，针对复杂问题给出清晰的排查方向，支撑问题闭环
• 整理排查案例，形成可复用经验
• ⚠️ 结论必须有明确的日志行号、时间戳作为证据支撑

3.4 日志合并与精简

• 当日志量过大、突破tokens限制时，通过工具对日志进行合并、去重、精简
• 保留核心异常信息和关键链路日志，剔除重复、无效日志
• 确保排查高效且不遗漏关键线索

四、辅助能力

4.1 问题拆解与协作

• 精准拆解用户描述的问题现象，抓取日志检索核心维度，提升排查针对性
• 与研发、业务等协作方清晰沟通，同步排查进度与线索，推动协同解决问题

4.2 产品与技术认知

• 熟悉软件核心业务流程与接口逻辑，结合业务场景判断日志异常的合理性
• 具备基础的网络、服务器、数据库常识，初步判断环境因素对日志异常的影响

4.3 工具与文档使用

• 熟练使用各类日志工具完成检索、合并、分析
• 使用Excel、WPS整理日志及排查记录，生成标准化报告
• 掌握远程协助、日志提取工具，高效获取目标日志，提升排查效率

五、常见问题及应对方法

问题1：日志量过大，检索缓慢、突破tokens限制

应对：

• 先通过工具筛选（指定时间段、核心关键词）缩小日志范围
• 对同类型、重复日志进行合并去重
• 提取日志核心字段（时间、报错信息、操作ID），剔除冗余字段，减少日志体积
• 使用 smart_log.py search --dedupe 智能去重

问题2：用户描述的时间点不在日志范围内

应对：

• 首先用 smart_log.py validate 确认日志实际时间范围
• 如果时间不匹配，询问用户是否有其他日志文件
• 日志截止时间本身可能就是问题发生时刻（进程退出导致日志停止）
• 检查是否有多个日志文件需要合并分析

问题3：日志无明确报错信息，无法定位异常

应对：

• 检索操作前后的上下文日志，排查是否有隐性异常（如参数缺失、接口返回空值）
• 结合业务流程，判断操作是否符合预期，排查流程中断点
• 使用 smart_log.py chain 分析事件链，还原问题发生链路
• 搜索 init/start/stop/exit 等状态变化关键词

问题4：日志格式不统一（混合JSON/文本），提取信息困难

应对：

• 使用jq、sed等工具标准化日志格式
• 优先提取结构化日志（JSON）的关键字段，非结构化日志通过正则表达式提取核心信息
• 将混合格式日志转换为统一格式后再进行分析

问题5：检索关键词不准确，遗漏关键日志

应对：

• 结合问题现象，扩展关键词（如报错的不同表述、相关接口名称、操作动作）
• 使用模糊检索、多关键词组合检索
• 排查日志中是否有同义异常提示，补充检索条件
• 参考上方"智能关键词推导"表扩展搜索范围

问题6：时间戳格式复杂，直接搜索匹配错误

应对：

• 先用 smart_log.py overview 确认日志的时间戳格式
• 根据实际格式构造精确的正则表达式
• 使用 \[15:40 或 ^15:40 等精确匹配避免误匹配

六、正例与反例（实战案例）

（一）正例：服务进程异常退出排查

场景：用户反馈"15:40 左右服务不可用，怀疑服务进程被异常停止"

正确排查步骤：

# 步骤1：获取日志概览
python3 tools/smart_log.py overview --file "/path/to/app.log"
# 输出：时间范围 14:33 - 15:36，发现日志在 15:36 截止

# 步骤2：验证时间范围
python3 tools/smart_log.py validate --file "/path/to/app.log" --time "15:40"
# 输出：⚠️ 目标时间 15:40 晚于日志结束时间 15:36:47

# 步骤3：分析日志截止前的错误情况
python3 tools/smart_log.py errors --file "/path/to/app.log" --start "15:25" --end "15:37" --top 20
# 发现：15:27 有 418 条错误，存在异常高峰

# 步骤4：搜索进程停止相关日志
python3 tools/smart_log.py search --file "/path/to/app.log" \
  --keyword "stop|exit|init|quit|shutdown" --start "15:27" --end "15:28" --context 3
# 发现：15:27:04 有 "STOP Service..." 和 "StopService" 日志

# 步骤5：重构事件链
python3 tools/smart_log.py chain --file "/path/to/app.log" \
  --start "15:27:00" --end "15:27:10" --events "stop,exit,init,instance,start"
# 输出：完整的启动→初始化失败→停止事件序列

结论输出：

## 📊 日志分析结论

### ⚠️ 重要发现
日志文件时间范围是 **14:33:59 - 15:36:47**，不包含 15:40。
日志在 **15:36:47** 停止，之后没有更多记录。

### 🔴 关键事件链（15:27 服务进程被停止）

| 时间 | 事件 | 说明 |
|------|------|------|
| 15:27:03.525 | 新进程启动 | PID 31224，参数 --mode=restart |
| 15:27:03.665 | InitInstance() return false | 管理程序初始化失败 |
| 15:27:04.881 | StopService 被调用 | 开始停止服务 |
| 15:27:04.884 | STOP Service... | 服务正在被停止 |

### 🔍 根因分析
**是的，服务进程在 15:27:04 被停止了。**

触发原因：
1. 15:27:03 - 系统启动了新的 app_tray.exe 进程
2. 该进程初始化失败（InitInstance() return false）
3. 初始化失败触发了服务停止流程

### 💡 建议
1. 检查为什么 app_tray.exe 初始化失败
2. 检查服务自身的日志文件获取更多细节
3. 如需分析 15:40 的情况，需要提供那个时间段的日志

（二）反例（错误操作）

场景：用户反馈"15:40 断网"

错误操作：

1. ❌ 直接搜索 grep "15:40" app.log，但日志时间戳格式是 [15:40:xx]，导致匹配到其他包含"15:40"的内容

2. ❌ 没有先确认日志时间范围，浪费时间搜索不存在的时间段

3. ❌ 只看 ERROR 级别日志，忽略了 INFO 级别中的"StopService"等关键状态变化

4. ❌ 只给出"网络有问题"的模糊结论，没有具体的日志证据和时间点

5. ❌ 没有注意到日志在 15:36 截止这个重要线索

七、网络异常排障流程

当用户反馈"连接突然断开"、"时间不固定"、"每个日志都可能有重要信息"时使用此流程。

7.1 快速排查三步法

# 步骤1：对所有日志做概览，确认格式识别正常（高价值日志 > 0）
python3 tools/smart_log.py overview --file "/path/to/client.log"

# 步骤2：用 --preset disconnect 一键搜索断连相关关键词
python3 tools/smart_log.py search --file "/path/to/client.log" \
  --preset disconnect --dedupe --limit 20

# 步骤3：对匹配结果中的时间点，用服务端日志交叉验证
python3 tools/smart_log.py search --file "/path/to/server.log" \
  --preset disconnect --start "10:43" --end "10:44" --dedupe --limit 10

7.2 预设关键词组

7.3 支持的日志格式

7.4 断连排障结论模板

## 断连排查结论

### 客户端日志
| 时间 | 事件 | 行号 | 日志摘要(≤200字符) |
|------|------|------|---------------------|
| 10:43:57 | DNS upstream closed | 10932 | `use of closed network connection` |

### 服务端日志
| 时间 | 事件 | 行号 | 日志摘要(≤200字符) |
|------|------|------|---------------------|
| 10:43:55 | Session reset | 8773 | `session force reset by peer` |

### 交叉验证
- 客户端 10:43:57 报 DNS closed → 服务端 10:43:55 已 reset session
- 时间差 2 秒，服务端先于客户端，断连由服务端发起

### 根因
[基于交叉验证的根因判断]

7.5 注意事项

• 多日志交叉验证：客户端日志 + 服务端日志必须按时间对齐分析
• 时间不固定场景：对所有日志逐个跑 --preset disconnect，每个有匹配的都要记录
• glog 格式特性：Go 程序日志可能全为 INFO 级别（glog I 前缀），不代表无异常——断连信息在 INFO 内容中
• 输出已截断：search 结果每条内容 ≤200 字符，行号+时间戳+截断内容，安全传递给 AI 模型分析

八、配套工具

智能日志分析工具（smart_log.py）

本技能的核心分析工具，专为处理大型日志文件设计。

工具路径

skills/log-analysis-troubleshooting/tools/smart_log.py

命令列表

使用示例

# 1. 获取日志概览（必做第一步）
python3 tools/smart_log.py overview --file "/path/to/app.log"

# 2. 验证时间范围
python3 tools/smart_log.py validate --file "/path/to/app.log" --time "15:40"

# 3. 智能搜索（带去重和上下文）
python3 tools/smart_log.py search --file "/path/to/app.log" \
  --keyword "error|fail|timeout" \
  --start "15:35" --end "15:45" \
  --dedupe --context 3

# 4. 错误聚类分析
python3 tools/smart_log.py errors --file "/path/to/app.log" \
  --start "15:35" --end "15:45" --top 20

# 5. 时间线分析
python3 tools/smart_log.py timeline --file "/path/to/app.log" \
  --start "15:35" --end "15:45" --events 30

# 6. 事件链分析
python3 tools/smart_log.py chain --file "/path/to/app.log" \
  --start "15:35" --end "15:45" \
  --events "start,stop,init,exit,connect,disconnect"

# 7. 追踪特定 ID
python3 tools/smart_log.py trace --file "/path/to/app.log" \
  --trace-id "req-12345" --context 3

# 8. 查看日志末尾（进程退出前最后记录）
python3 tools/smart_log.py tail --file "/path/to/app.log" --lines 50

基础 Shell 工具

日志合并核心方法（解决tokens超限问题）

• 方法1：按异常类型合并 —— 将同类型报错的日志合并，保留1条完整报错日志+其他日志的关键信息（时间、用户ID），剔除重复的报错堆栈

• 方法2：按时间段合并 —— 将同一时间段（如每10分钟）的日志合并，提取该时间段内的异常类型、影响数量，无需保留每条日志的完整内容

• 方法3：字段精简合并 —— 只保留日志中的核心字段（时间、异常类型、接口/操作ID、用户ID），删除冗余描述、无关参数，缩小日志体积

• 方法4：智能去重 —— 使用 smart_log.py search --dedupe，自动识别重复模式，只保留代表性样本

九、行为准则

1. 遵循六步排查法：概览 → 时间校验 → 范围定位 → 异常聚类 → 事件链重构 → 根因定位

2. 先确认时间范围：任何搜索前，必须先确认日志的实际时间覆盖范围

3. 精确匹配时间戳：根据日志实际格式构造正则，避免误匹配

4. 排查全程留存日志证据：所有判断必须基于实际日志内容，确保可追溯

5. 结构化输出结论：使用表格、时间线等形式清晰展示分析结果

6. 不提出不必要的问题：主动提供全面的日志分析结果及排查建议

7. 日志截止时间是重要线索：进程退出可能导致日志停止写入

8. 当日志量过大时：优先使用 smart_log.py --dedupe 进行智能去重

9. 禁止重复执行（防死循环铁律）：

   • 同一文件、同一命令、同一参数的组合，不得重复执行——如果上次有结果，直接用上次的结果
   • 同一文件的 overview 只需执行 1 次，后续分析直接引用结果
   • 连续 2 次工具调用未能获得新信息时，立即停止搜索，基于已有证据输出结论
   • 如果觉得"上次没看全"，改用不同命令或不同参数（如换 tail 替代重复 search），而非重复同一命令
   • 排障最多 15 次工具调用，超过后必须输出当前结论

🔴🔴🔴 日志证据原则（最高优先级）🔴🔴🔴

所有分析结论必须有日志证据支撑，严禁臆造！

核心要求

证据标准

有效证据:
  ✅ 检索到了具体的日志条目
  ✅ 引用了关键日志行（包含时间戳和行号）
  ✅ 分析了日志中的错误码/异常信息
  ✅ 展示了时间线上的事件序列

无效证据:
  ❌ 仅凭问题描述推断（"断网应该是网络问题"）
  ❌ 基于经验推断（"这种情况一般是配置错误"）
  ❌ 未检索就下结论（"根据常见原因分析..."）
  ❌ 编造日志内容（未实际检索到的日志）

强制自检清单

在输出任何结论前，必须确认：

□ 我是否实际使用 smart_log.py 检索了相关日志？
□ 我的结论是否基于具体的日志条目（有行号、有时间戳），而非推测？
□ 如果用户追问"你怎么知道的"，我能引用具体日志行吗？
□ 我是否区分了"日志中记录的"和"我认为应该是"？
□ 我是否遵循了六步排查法，而非跳步直接结论？