# Log Analysis Troubleshooting

> 当用户需要使用日志排查软件问题时，主动检索、筛选并分析日志内容；识别异常、定位根因，并提供清晰的排查方向。适用于处理日志相关排查任务，包括关键词检索、异常识别、根因分析等场景。可解决日志量大、检索低效、异常定位模糊等问题，提供工具适配及日志合并方案，辅助高效完成排查。

- Skill: `infometa/log-analysis-troubleshooting` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add infometa/log-analysis-troubleshooting`
- Raw SKILL.md: https://api.skillmd.com/api/skills/infometa/log-analysis-troubleshooting/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: infometa (https://skillmd.com/u/infometa)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/infometa/log-analysis-troubleshooting

---


# 日志分析与排查技能

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

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

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

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

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

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

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

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

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

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

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

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

#### 第一步：概览分析（Overview）

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

**执行方式**：
```bash
python3 tools/smart_log.py overview --file "/path/to/app.log"
```

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

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

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

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

**执行方式**：
```bash
# 使用 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）

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

**执行方式**：
```bash
python3 tools/smart_log.py timeline --file "/path/to/app.log" --start "15:35" --end "15:40"
```

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

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

| 日志格式示例 | 搜索 15:40 的正则 |
|-------------|------------------|
| `[INFO][15:40:23.456]` | `\[15:40` |
| `2024-02-06 15:40:23 INFO` | `15:40:` |
| `15:40:23.456 [INFO]` | `^15:40` |

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

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

**执行方式**：
```bash
python3 tools/smart_log.py errors --file "/path/to/app.log" --start "15:35" --end "15:40" --top 20
```

**分析技巧**：
- 关注突然激增的错误类型
- 对比正常时段和异常时段的错误分布
- 注意错误之间的时序关系

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

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

**执行方式**：
```bash
# 推荐：使用 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
```

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

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

**结论模板**：
```markdown
## 📊 日志分析结论

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

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

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

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

### 2.2 智能关键词推导

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

| 问题类型 | 推导关键词 |
|----------|-----------|
| 断网/网络问题 | disconnect, timeout, unreachable, network, connection, refused |
| 进程退出 | exit, quit, stop, terminate, crash, killed, signal, shutdown |
| 登录失败 | auth, login, fail, denied, unauthorized, 401, 403 |
| 配置问题 | config, invalid, parse error, load, init, missing |
| 性能问题 | slow, timeout, latency, queue, backlog, OOM, memory |
| 通用异常 | error, warn, fail, exception, critical, fatal |

## 三、核心能力

### 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 左右服务不可用，怀疑服务进程被异常停止"

**正确排查步骤**：

```bash
# 步骤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"
# 输出：完整的启动→初始化失败→停止事件序列
```

**结论输出**：

```markdown
## 📊 日志分析结论

### ⚠️ 重要发现
日志文件时间范围是 **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 快速排查三步法

```bash
# 步骤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 预设关键词组

| 预设名 | 覆盖关键词 | 适用场景 |
|--------|-----------|----------|
| `disconnect` | disconnect, reconnect, close, closed, reset, broken, drop, timeout, refuse, refused, dead, lost, abort, shutdown, detach, bye | 断连/重连排查（默认首选） |
| `error` | error, fail, failed, failure, panic, fatal, crash, exception | 错误聚类排查 |
| `network` | timeout, refuse, reset, broken, drop, unreachable, dns, proxy, tls, ssl, cert | 网络层排查 |
| `auth` | auth, denied, unauthorized, forbidden, token, login, logout, expire | 认证/权限排查 |

### 7.3 支持的日志格式

| 格式 | 示例 | 说明 |
|------|------|------|
| **glog** | `I0617 10:35:32.640599 4304 service.go:120] msg` | Go 程序常用 |
| 标准 [LEVEL][time] | `[ERROR][2024-01-01 15:40:23.456]` | 通用 |
| ISO 8601 | `2024-01-01T15:40:23.456Z` | 标准 |
| 自定义时间戳 | `[ INFO][15:12:01.877][app.exe 3556.3560][module.cpp@234]` | 多模块程序 |

### 7.4 断连排障结论模板

```markdown
## 断连排查结论

### 客户端日志
| 时间 | 事件 | 行号 | 日志摘要(≤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
```

#### 命令列表

| 命令 | 用途 | 典型场景 |
|------|------|----------|
| `overview` | 获取日志概览 | 排查第一步，了解基本情况 |
| `validate` | 时间范围验证 | 确认目标时间是否在日志中 |
| `search` | 智能搜索（支持去重） | 搜索特定关键词/时间段 |
| `search --preset disconnect` | 预设关键词搜索 | 断连排查一键搜索 |
| `errors` | 错误聚类分析 | 了解错误分布，识别主要问题 |
| `timeline` | 时间线分析 | 查看关键事件时序 |
| `chain` | 事件链分析 | 重构问题发生链路 |
| `tail` | 查看末尾N行 | 进程退出前最后日志、快速验证日志截止点 |
| `trace` | ID 追踪 | 追踪特定请求/会话 |

#### 使用示例

```bash
# 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 工具

| 工具 | 核心用途 | 示例 |
|------|----------|------|
| `grep` | 关键词搜索 | `grep -n "error" app.log` |
| `grep -c` | 统计匹配行数 | `grep -c "\[15:40" app.log` |
| `grep -iE` | 多关键词搜索 | `grep -iE "err\|fail\|timeout" app.log` |
| `head` | 查看开头 | `head -50 app.log` |
| `tail` | 查看结尾 | `tail -100 app.log` |
| `wc -l` | 统计行数 | `wc -l app.log` |
| `awk` | 字段提取 | `awk '{print $1,$3}' app.log` |
| `sed` | 格式转换 | `sed 's/old/new/g' app.log` |
| `jq` | JSON 解析 | `cat app.log \| jq '.error'` |

### 日志合并核心方法（解决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 次工具调用**，超过后必须输出当前结论

---

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

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

### 核心要求

| 要求 | 说明 | 违规示例 |
|------|------|---------|
| **有据可查** | 每个结论必须指向具体的日志条目 | ❌ "可能是网络问题" |
| **禁止推测** | 不能基于经验或常识推断根因 | ❌ "通常这种情况是..." |
| **禁止臆造** | 不能编造不存在的日志内容 | ❌ 未检索就描述日志细节 |
| **证据先行** | 先找到日志，再得出结论 | ❌ 先下结论再找日志 |

### 证据标准

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

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

### 强制自检清单

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

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