日志排查工作流

Skill 标识
log-analysis-skill

看到 ERROR 之后,下一步查什么?用七步工作流提取关键词、梳理调用链、定位可疑模块,输出有证据的排查建议。跟着订单失败案例,把日志阅读变成可复用的分析能力。

扫码添加辅导员,发送 Skill 名称领取源码
本文目录
  1. Skill 概览
  2. 适合谁、用在什么场景
  3. 需要准备什么、能得到什么
  4. 核心能力与使用边界
  5. 实战教程与使用说明
  6. 一、为什么测试人必须会读日志?
  7. 1.1 常见误区:只报现象,不给方向
  8. 1.2 日志排查工作流的目标
  9. 动手做 ①
  10. 二、为什么日志分析必须工作流化?
  11. 2.1 不能靠「感觉」看 ERROR
  12. 2.2 同一段日志,新手 vs 高级测试
  13. 三、日志排查工作流总览(7 步)
  14. 四、七步详解(含模板与案例)
  15. 4.1 第一步:日志关键词提取
  16. 动手做 ②
  17. 4.2 第二步:异常类型识别
  18. 4.3 第三步:调用链分析
  19. 4.4 第四步:模块定位
  20. 4.5 第五步:历史日志规律匹配
  21. 4.6 第六步:排查建议输出
  22. 4.7 第七步:证据不足时如何处理
  23. 五、完整跟做案例:订单创建失败
  24. 5.1 输入
  25. 5.2 按 7 步填写(学员可先手写,再对照下方参考答案)
  26. 动手做 ③
  27. 六、从零编写 workflows/log_analysis.md
  28. 6.1 目录准备
  29. 6.2 Workflow 文件模板(可直接复制修改)
  30. 6.3 在 SKILL.md 中注册
  31. 七、常见错误与自查表
  32. 八、课堂练习(含参考答案)
  33. 8.1 题目
  34. 8.2 参考答案
  35. 动手做 ④
  36. 九、本节总结
  37. 附录 A:学习前可准备的附件资料
  38. A.1 日志样例(assets/sample_logs/)
  39. A.2 规则与资产库(references/)
  40. A.3 输出模板(assets/templates/)
  41. A.4 工具与环境(可选)
  42. A.5 课前自检
  43. 附录 B:备注与延伸

Skill 概览

适合谁、用在什么场景

需要完成第一轮问题定位并与开发沟通的测试工程师。

需要准备什么、能得到什么

  • 输入材料:脱敏日志片段、异常时间、业务现象及可选的模块图与历史案例。
  • 交付产物:关键词、异常类型、调用链线索、疑似模块及分级排查建议。

核心能力与使用边界

  • 核心能力:按七步组织分析,区分事实、候选原因和证据缺口,并将流程写入工作流文件。
  • 使用边界:日志不足时应补证据;不能仅凭 ERROR 或 timeout 就断言根因,也不替开发直接修复代码。

实战教程与使用说明

一、为什么测试人必须会读日志?

1.1 常见误区:只报现象,不给方向

场景:用户提交订单后,页面提示「系统异常」。

写法

价值

❌ 提交订单失败,请开发查看

开发需从零排查,测试价值低

✅ 日志出现 connection timeout,疑似订单服务调用库存服务超时,建议优先检查库存服务连接、接口耗时、TraceId 链路

缩小排查范围,加快定位

1.2 日志排查工作流的目标

不是让测试人替开发定位代码行号。
而是让测试人借助 AI 更快判断:

  • 问题大致方向(网络 / 数据库 / MQ / 业务)

  • 影响模块(订单 / 支付 / 库存)

  • 回归范围与风险等级

动手做 ①

找一条你最近遇到的报错日志(可脱敏),用一句话描述:如果只报 Bug 现象 vs 补充日志方向,开发收到后的差异是什么?


二、为什么日志分析必须工作流化?

2.1 不能靠「感觉」看 ERROR

真实日志排查通常要经过:

text
关键词提取 → 异常类型识别 → 调用链分析 → 模块定位
    → 历史规律匹配 → 排查建议输出 →(证据不足时)补充采集建议

2.2 同一段日志,新手 vs 高级测试

原始片段:

text
ERROR
timeout
order-service
inventory-service
traceId=abc123

视角

会看到什么

新人

「报错了」

高级测试

订单服务?库存服务?接口超时还是 DB 慢?traceId 能否串起全链路?

结论:日志排查工作流 = 把「看日志经验」拆成 AI 可逐步执行的分析路径。


三、日志排查工作流总览(7 步)

text
① 输入日志(+ 时间、环境、业务场景、traceId)
    ↓
② 日志关键词提取
    ↓
③ 异常类型识别
    ↓
④ 调用链分析
    ↓
⑤ 模块定位
    ↓
⑥ 历史日志规律匹配(references)
    ↓
⑦ 排查建议输出
    ↓
⑧ 证据不足 → 列出缺失信息 + 补充采集建议(不硬猜根因)

原则:AI 不应一上来就给根因,应先拆清日志,再逐步收敛方向。


四、七步详解(含模板与案例)

4.1 第一步:日志关键词提取

Goal:从噪音中提取「信号」,先不解释原因。

关键词类型清单(可写入 references/log_keyword_types.md):

类型

示例

错误级别

ERROR、WARN、FATAL

异常关键词

timeout、exception、failed、refused、denied

服务名称

order-service、payment-service、inventory-service

链路标识

traceId、requestId、spanId

接口路径

/api/order/create

时间信息

发生时间、耗时、时间窗口

案例

原始日志:

text
2026-05-20 10:21:30 ERROR order-service traceId=abc123
Call inventory-service failed: java.net.SocketTimeoutException: Read timed out

AI 提取后(结构化输出):

yaml
level: ERROR
source_service: order-service
downstream_service: inventory-service
exception_keywords:
  - SocketTimeoutException
  - Read timed out
trace_id: abc123
preliminary_direction: 订单服务调用库存服务读取超时

动手做 ②

用你自己的一条日志,按上表填一份 YAML 关键词提取结果。


4.2 第二步:异常类型识别

Goal:从「看到错误」升级到「判断错误类别」。

常见异常类型表(references/exception_type_map.md):

类别

典型关键词

常见排查方向

系统异常

NullPointerException、IndexOutOfBounds

空指针、数组越界、代码分支

网络异常

timeout、connection refused、reset

下游慢、网络、连接池

数据库异常

deadlock、lock wait timeout、duplicate key

锁、索引、幂等、慢 SQL

缓存异常

Redis timeout、cache miss、pool exhausted

Redis、连接池、热点 key

MQ 异常

send failed、consumer error、retry

消费重复、堆积、死信

权限异常

401、403、permission denied

鉴权、角色、Token

业务异常

库存不足、订单状态非法

业务规则、状态机

案例:日志含 duplicate key

yaml
exception_type: 数据库唯一键冲突
common_causes:
  - 重复提交
  - 幂等控制不足
  - MQ 重复消费
suggested_checks:
  - 请求是否重复
  - 唯一索引字段
  - MQ 消费记录

4.3 第三步:调用链分析

Goal:找到异常发生在链路的哪个环节,而不是直接猜根因。

订单创建链路示例:

text
用户请求 → 网关 → 订单服务 → 库存服务 → 库存数据库

日志:order-service call inventory-service timeout

可能原因(需证据支撑,不可单点定论):

  • 库存服务响应慢

  • 库存数据库慢查询

  • 网络连接异常

  • 订单服务超时配置过短

AI 输出结构模板:

yaml
entry: 订单创建接口
upstream: 网关
current: 订单服务
downstream: 库存服务
failure_node: 订单服务 → 库存服务 调用
preliminary: 库存服务或库存数据层存在响应超时风险

4.4 第四步:模块定位

Goal:定位到业务/技术模块,明确找谁、回归哪里。

四个定位维度:

维度

示例

按服务

订单服务、支付服务、库存服务

按业务

下单、支付、库存扣减、优惠券核销

按技术

数据库、Redis、MQ、第三方接口

按环境

测试、预发、生产

案例

text
payment-service ERROR callback failed, update order status failed

AI 定位输出:

yaml
business_module: 支付回调
related_modules: [订单状态更新]
tech_direction: [数据库更新, MQ 通知]
focus_services: [payment-service, order-service]
focus_tables: [支付流水表, 订单状态表]

4.5 第五步:历史日志规律匹配

Goal:从「通用分析」升级为「项目经验分析」。

在 references/log_pattern_history.md 中维护规律库,例如:

markdown
| 日志特征 | 常见原因 | 建议先看 |
|----------|----------|----------|
| connection refused | 下游未启动、地址错误、网络不通 | 服务健康检查、注册中心 |
| duplicate key | 重复提交、幂等失败、MQ 重复消费 | 订单号生成、消费位点 |
| lock wait timeout | 事务未释放、并发更新同一行 | 锁等待、事务日志 |
| Redis timeout | 连接池耗尽、Redis 阻塞、网络抖动 | Redis 监控、慢命令 |

当前日志:duplicate key 'order_no_123'

匹配结果:

yaml
matched_pattern: 唯一键冲突
high_frequency_causes:
  - 重复创建订单
  - 重复消费消息
  - 幂等校验缺失
checks:
  - 订单号生成逻辑
  - MQ 消费记录
  - 接口重复提交日志

4.6 第六步:排查建议输出

Goal:输出可执行建议,而非「可能是服务异常」。

标准输出结构(写入 workflow 的「最终输出」节):

text
1. 异常摘要
2. 异常类型
3. 疑似模块
4. 建议查看的日志(服务名 + traceId + 时间窗)
5. 建议检查的接口 / SQL / 数据
6. 建议验证步骤
7. 风险等级(P0/P1/P2 + 理由)

完整案例输出(订单调用库存超时):

markdown
## 日志排查报告

**异常摘要**:订单服务调用库存服务发生读取超时(SocketTimeoutException: Read timed out)

**异常类型**:网络 / 接口调用超时

**调用链**:用户请求 → 订单服务 → 库存服务(异常节点)

**疑似模块**:库存服务、库存数据库、订单服务调用链配置

**建议日志**:
- inventory-service,traceId=abc123,时间窗 10:21:25–10:21:35
- order-service 接口耗时日志

**建议 SQL**:检查库存表慢查询、锁等待

**验证步骤**:同场景重试下单,对比 traceId 各节点耗时

**风险等级**:P1 — 可能影响下单成功率

4.7 第七步:证据不足时如何处理

原则:专业 AI 在证据不足时不硬猜根因,而是列出缺失信息与采集建议。

错误输出

正确输出

可能是数据库问题

当前证据不足,无法判断根因。建议补充:完整 traceId 链路、请求参数、响应体、订单号、时间窗、下游日志

缺失信息清单(workflow 中可做成 checklist):

text
- [ ] 缺少 traceId / requestId
- [ ] 缺少请求参数
- [ ] 缺少接口响应
- [ ] 缺少上下游服务日志
- [ ] 缺少发生时间范围
- [ ] 缺少环境信息(测试/预发/生产)
- [ ] 缺少版本变更说明

五、完整跟做案例:订单创建失败

5.1 输入

text
2026-05-20 10:21:30 ERROR order-service traceId=abc123
Create order failed. Call inventory-service timeout.
java.net.SocketTimeoutException: Read timed out

补充输入(建议一并提供):

yaml
occurred_at: "2026-05-20 10:21:30"
environment: production
business_scene: 用户下单创建订单
trace_id: abc123

5.2 按 7 步填写(学员可先手写,再对照下方参考答案)

参考答案对照:

步骤

内容

① 关键词

ERROR、order-service、inventory-service、SocketTimeoutException、Read timed out、traceId=abc123

② 异常类型

网络 / 接口调用超时

③ 调用链

用户请求 → 订单服务 → 库存服务

④ 模块定位

疑似库存服务响应超时,可能关联库存 DB 或接口性能

⑤ 历史规律

timeout 常见于下游慢、慢 SQL、连接池不足、网络波动

⑥ 排查建议

查 inventory-service 同 traceId 日志;库存接口耗时;库存库慢 SQL;订单服务超时配置

⑦ 风险

P1,可能影响订单创建成功率

动手做 ③

在本地创建 assets/sample_logs/order_create_timeout.log,把上面日志写入,并运行一次你 Skill 中的日志分析 workflow(或让 AI 严格按 workflow 输出报告)。


六、从零编写 workflows/log_analysis.md

6.1 目录准备

bash
mkdir -p my-test-skill/workflows my-test-skill/references my-test-skill/assets/sample_logs
touch my-test-skill/workflows/log_analysis.md

6.2 Workflow 文件模板(可直接复制修改)

markdown
# Log Analysis Workflow

## Purpose
对测试/生产日志做结构化第一轮分析,输出可执行排查建议。

## When to use
- 用户提供原始日志、报错截图文字、ELK 导出片段
- Bug 描述含「超时」「异常」「failed」「traceId」等

## Required Inputs
- raw_log(必填):原始日志文本
- occurred_at(建议):发生时间
- environment(建议):test / staging / prod
- business_scene(建议):如「下单」「支付回调」
- trace_id / request_id(强烈建议)

## 执行步骤

### Step 1:提取日志关键词
**Goal**:输出结构化关键词,不写根因猜测。
**必须引用**:`references/log_keyword_types.md`
**Checkpoint**:
- [ ] 已提取级别、服务名、异常词、链路 ID、时间

### Step 2:识别异常类型
**Goal**:归类到网络/DB/MQ/缓存/权限/业务等。
**必须引用**:`references/exception_type_map.md`

### Step 3:调用链分析
**Goal**:标出 entry、上下游、异常节点。
**Checkpoint**:
- [ ] 未在无证据时断言「就是 XX 服务 bug」

### Step 4:模块定位
**Goal**:业务模块 + 技术模块 + 建议关注服务/表。

### Step 5:匹配历史规律
**必须引用**:`references/log_pattern_history.md`
**若无匹配**:明确写「无历史匹配,建议将本案入库」

### Step 6:输出排查建议
**输出模板**:`assets/templates/log_analysis_report.md`

### Step 7:证据不足处理
**规则**:若 raw_log 少于 3 类有效信号(级别/服务/异常词/traceId 等),禁止输出根因,只输出「缺失信息清单」。

## 人工复核点
- [ ] 排查建议是否具体到「查哪条日志、哪个 traceId」
- [ ] 风险等级是否与业务影响一致
- [ ] 是否避免无证据的根因结论

## Final Output
使用 `assets/templates/log_analysis_report.md` 结构输出。

6.3 在 SKILL.md 中注册

markdown
当用户要求分析日志、排查报错、解读 traceId 时:
1. 读取本 Skill
2. **严格按** `workflows/log_analysis.md` 执行,不得跳步
3. 标注「必须引用」的 references 文件必须加载

七、常见错误与自查表

错误

表现

修复

直接判根因

跳过关键词与类型

强制 Step 1–2 先输出结构化信息

只看一行日志

忽略调用链

增加 Step 3,要求画链路

异常类型混为一谈

timeout 与 duplicate key 都叫「系统异常」

维护 exception_type_map.md

不用历史规律

每次从零分析

维护 log_pattern_history.md

证据不足仍下结论

「可能是数据库」

启用 Step 7 缺失清单

口诀:有证据、有步骤、不拍脑袋。


八、课堂练习(含参考答案)

8.1 题目

分析以下日志,按 workflow 输出完整报告:

text
ERROR payment-service traceId=p987
update order status failed: lock wait timeout exceeded

要求包含:关键词、异常类型、调用链推测、疑似模块、历史规律、排查建议、需补充的信息。

8.2 参考答案

yaml
keywords:
  - payment-service
  - update order status failed
  - lock wait timeout exceeded
  - traceId=p987
exception_type: 数据库锁等待超时
call_chain_guess: 支付回调 → 更新订单状态 → 订单库
suspected_modules: [支付回调, 订单状态更新, 订单数据库]
history_match: 并发更新订单状态、事务未释放、索引不合理
suggestions:
  - 查订单表锁等待与 innodb 状态
  - 查支付回调是否重复触发
  - 查事务提交与回滚日志
missing_info:
  - 订单号
  - traceId 完整链路日志
  - SQL 执行日志
  - 并发请求记录
risk: P1(支付与订单状态一致性)

动手做 ④

将本题答案整理成 assets/templates/log_analysis_report.md 的一份实例,保存为 assets/examples/payment_lock_timeout_report.md。


九、本节总结

text
日志排查工作流 =
    关键词提取
  + 异常类型识别
  + 调用链分析
  + 模块定位
  + 历史规律匹配
  + 排查建议输出
  + 证据不足时的补充采集建议

最终观点:测试人不一定要替开发修代码,但必须能借助 AI 完成第一轮日志分析,快速判断问题方向、影响模块与下一步排查路径。


附录 A:学习前可准备的附件资料

A.1 日志样例(assets/sample_logs/)

文件名

内容说明

order_create_timeout.log

订单调库存超时(本教程主案例)

duplicate_key_order.log

duplicate key 唯一键冲突

payment_lock_timeout.log

课堂练习:支付更新订单锁等待

connection_refused.log

connection refused 下游不可用

redis_timeout.log

Redis timeout / 连接池

mq_consumer_error.log

MQ 消费失败 / 重试

minimal_error_only.log

仅一行 ERROR order failed(练证据不足)

A.2 规则与资产库(references/)

文件名

内容说明

log_keyword_types.md

关键词类型与提取规则

exception_type_map.md

异常类型 → 常见原因 → 排查方向

log_pattern_history.md

项目历史日志规律库(持续沉淀)

service_call_chain.md

核心链路图(下单/支付/库存等)

module_owner_map.md

模块 → 负责人 / 值班(可选)

A.3 输出模板(assets/templates/)

文件名

用途

log_analysis_report.md

标准日志排查报告结构

missing_evidence_checklist.md

证据不足时的缺失清单

A.4 工具与环境(可选)

准备项

说明

ELK / 云日志平台账号

能按 traceId、时间窗查询

脱敏后的真实日志 3~5 条

来自当前项目,练习更准确

Cursor + Skill 目录

编辑 workflow 与 references

Git

版本管理 workflow 与规律库迭代

A.5 课前自检

  • 已准备至少 2 条真实或仿真日志(含 traceId 更佳)

  • 已创建 workflows/、references/、assets/sample_logs/

  • 已草拟 references/log_pattern_history.md(至少 5 条规律)

  • 知晓本 Skill 在 SKILL.md 中的触发条件


附录 B:备注与延伸

  1. 与 Bug 分析 workflow 的关系:日志排查常作为 workflows/bug_analysis.md 的子步骤;也可独立成 Skill,由 SKILL.md 按场景路由。

  2. 规律库迭代:每次线上事故复盘,将「日志特征 → 根因 → 修复」追加到 log_pattern_history.md,AI 会越用越准。

  3. 安全:样例日志须脱敏(用户 ID、手机号、订单号可哈希或替换)。

  4. 边界:workflow 输出的是「排查方向」,最终根因仍须研发结合代码与监控确认;测试人在人工复核点签字把关。

本节课对应的skill全文档:

开始使用 log-analysis-skill

扫码添加辅导员,发送 Skill 名称,领取源码与配套资料。

同类 Skills