log-analysis-troubleshooting

name	log-analysis-troubleshooting
version	1.5.0
triggers	["应用日志","错误日志","访问日志","故障排查","日志分析"]
description	当用户需要使用日志排查软件问题时，主动检索、筛选并分析日志内容；识别异常、定位根因，并提供清晰的排查方向。适用于处理日志相关排查任务，包括关键词检索、异常识别、根因分析等场景。可解决日志量大、检索低效、异常定位模糊等问题，提供工具适配及日志合并方案，辅助高效完成排查。
allowed-tools	grep, awk, ELK, cat, sed, jq, Logstash, Kibana, Splunk, Grafana, tail, head, wc, smart_log.py

日志分析与排查技能

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

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

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

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

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

• 日志量超限处理：日志量过大（突破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"

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

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

日志格式示例	搜索 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）

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

执行方式：

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 智能关键词推导

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

问题类型	推导关键词
断网/网络问题	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 左右服务不可用，怀疑服务进程被异常停止"

正确排查步骤：

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

预设名	覆盖关键词	适用场景
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 断连排障结论模板

## 断连排查结论

### 客户端日志
| 时间 | 事件 | 行号 | 日志摘要(≤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 追踪	追踪特定请求/会话

使用示例

# 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 次工具调用，超过后必须输出当前结论

---

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

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

核心要求

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

证据标准

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

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

强制自检清单

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

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