日志分析

何时使用

• 线上报错、接口失败、任务失败,需要从日志里找原因;
• 用户说"帮我查下日志""这个报错对应的日志在哪";
• 故障涉及多个服务,需要把日志串起来;
• 排查"偶发失败""高峰期出错"这类难复现的问题。

使用步骤

第 1 步:确定范围

先问清:

1. 故障现象和时间窗口(几点开始、几点结束);
2. 涉及的服务和模块;
3. 有没有已知的报错信息或请求 ID。

第 2 步:抽取错误关键字

按优先级搜索,不要从头到尾读日志:

# 高频错误词
grep -iE "error|exception|timeout|failed|oom|panic" app.log

# 按时间窗过滤
sed -n '/2026-08-29 14:00/,/2026-08-29 14:30/p' app.log

# 结构化日志用 jq
cat app.log | jq 'select(.level == "ERROR")'

高价值关键字:error、exception、timeout、OOM、panic、deadlock、connection refused。

第 3 步:重建时间线

检索命令、常见日志模式速认和脱敏规则见 references/SEARCH_COMMANDS.md。

• 按时间排序整理关键事件;
• 记录每个事件的:时间、服务、级别、消息;
• 确认日志时间源一致(跨机器要统一 NTP,否则关联会乱);
• 把"先发生了什么、后发生了什么"理清楚。

第 4 步:关联上下游

用关联字段把日志串起来:

• request_id / trace_id / span_id;
• 用户 ID、订单 ID 等业务主键;
• 服务名 + 时间窗口。

定位链路:

入口服务 → 下游服务 → 数据库/缓存/第三方

看失败发生在链路的哪一环,谁先抛的错,谁只是跟着报错。

第 5 步:输出分析报告

# 日志分析报告

## 时间窗口与范围
## 关键事件时间线
## 关联链路
## 根因
## 证据(关键日志行)
## 建议

输入与输出

• 输入:日志文件/日志查询权限 + 故障信息;
• 输出:时间线 + 关联链路 + 根因结论。

示例

现象: 14:00-14:10 下单接口大量 500。

抽取: 所有 500 响应对应的请求 ID 集中在同一个下游服务超时。

时间线:

14:00:01 订单服务调用支付服务超时(第一次)
14:00:03 支付服务连接池报 connection refused
14:00:05 订单服务重试,连续失败
14:02:00 支付服务日志显示 OOM,进程重启

根因: 支付服务内存泄漏导致 OOM 重启,期间所有调用失败。

建议: 修泄漏 + 加内存告警 + 调用方加熔断。

辅助脚本

scripts/log_correlator.py 按关联字段把分散日志串起来(支持 JSON 行和纯文本):

python scripts/log_correlator.py app.log --field trace_id --value abc123

脚本只做筛选,结论需要人确认。

注意事项

• 日志是证据,结论必须能指到具体日志行;
• 不要只读最后几行,时间窗内的错误要全看;
• 区分"根因"和"症状":跟着报错的不一定是源头;
• 日志缺失时说明缺失,不脑补;
• 涉及敏感信息的日志,输出报告时脱敏。

不适用场景

• 没有日志访问权限或文件;
• 问题是性能优化(走 performance-profiler);
• 本地环境问题(走 dev-env-troubleshooter)。

验证方式

1. 触发:"帮我查下日志""这个报错怎么回事";
2. 检查:报告含时间线、关联链路、根因和日志证据;
3. 复核:对照原始日志,确认每条结论都有出处。