---

name: reading-logs description: 通过定向搜索和迭代优化高效分析日志。用于调查错误、调试事件或分析应用日志中的模式。

分析日志

铁律： 先过滤，后读取。永远不要在没有缩小范围的情况下打开大型日志文件。

核心原则

1. 先过滤 - 在阅读前进行搜索/过滤
2. 迭代缩小 - 从广泛开始（严重性），用模式/时间细化
3. 小上下文窗口 - 获取匹配项周围的5-10行，而不是整个文件
4. 总结胜过转储 - 简洁地呈现发现，而不是原始输出

工具策略

1. 查找日志（Glob）

**/*.log
**/logs/**
**/*.log.*  # 轮转日志

2. 使用Grep过滤

# 严重性搜索
grep -Ei "error|warn" app.log

# 排除噪音
grep -i "ERROR" app.log | grep -v "known-benign"

# 匹配项周围的上下文
grep -C 5 "ERROR" app.log  # 前后5行

# 时间窗口
grep "2025-12-04T11:" app.log | grep "ERROR"

# 计数出现次数
grep -c "connection refused" app.log

3. 与Bash链式操作

# 仅最近
tail -n 2000 app.log | grep -Ei "error"

# 顶部重复
grep -i "ERROR" app.log | sort | uniq -c | sort -nr | head -20

4. 最后读取

只有在用Grep缩小范围后才读取。使用上下文标志（-C、-A、-B）来抓取目标块。

调查工作流程

单一事件

1. 获取时间窗口、错误文本、相关ID
2. 查找覆盖该时间的日志（Glob）
3. 时间窗口grep：grep "2025-12-04T11:" service.log | grep -i "timeout"
4. 按ID追踪：grep "req-abc123" *.log
5. 扩展上下文：grep -C 10 "req-abc123" app.log

重复模式

1. 按严重性过滤：grep -Ei "error|warn" app.log
2. 分组和计数：grep -i "ERROR" app.log | sort | uniq -c | sort -nr | head
3. 排除已知噪音
4. 使用上下文深入顶部模式

红色标志

• 不经过滤打开大于10MB的文件
• 在Grep前使用Read
• 转储原始输出而不总结
• 在多日日志上搜索时没有时间限制

实用脚本

对于复杂操作，使用 scripts/ 中的脚本：

# 按频率聚合错误（规范化时间戳/ID）
bash scripts/aggregate-errors.sh app.log "ERROR" 20

# 按类型提取和分组堆栈跟踪
bash scripts/extract-stack-traces.sh app.log "NullPointer"

# 使用jq过滤器解析JSON日志
bash scripts/parse-json-logs.sh app.log 'select(.level == "error")'

# 显示错误随时间分布（小时/分钟桶）
bash scripts/timeline.sh app.log "ERROR" hour

# 追踪请求ID跨多个日志文件
bash scripts/trace-request.sh req-abc123 logs/

# 按持续时间查找慢操作
bash scripts/slow-requests.sh app.log 1000 20

输出格式

1. 说明您搜索了什么（文件、模式）
2. 提供简短的片段说明问题
3. 解释可能发生了什么以及原因
4. 建议下一步步骤