Gc Log Report

SKILL.md

---
name: gc-log-report
description: 读取和分析 JDK GC 日志，并生成更专业的 HTML 正式报告与 Markdown 简版结论，既适合技术复盘，也适合领导汇报和架构师调优决策。只要用户提到 gc log、GC 日志、CMS/G1/ParNew 回收日志、JVM 停顿分析、Full GC、Young GC、生成 GC 分析报告、导出 HTML 报告、整理领导汇报材料、给出 JVM 调优建议、识别问题项并高亮展示，或希望合并多个 gc.log.* 滚动文件并给出结论时，都应该优先使用这个 skill，即使用户没有明确说“skill”或“报告”。
---

# GC Log Report

用于把 JDK GC 日志整理成可读、可汇报、可复核、可指导调优的分析报告。

这个 skill 适合以下场景：
- 用户给了一个或多个 `gc.log*` 文件，希望分析 GC 行为
- 用户想知道是否存在 Full GC、Young GC 频繁、长暂停、老年代压力等问题
- 用户要一份适合发领导的结论，不想只看原始日志
- 用户希望为架构师、性能负责人或中间件负责人提供 JVM 调优依据
- 用户希望输出为 HTML 报告、Markdown 简报，或者同时输出两者
- 用户给的是滚动日志集合，希望合并后形成完整时间窗报告
- 用户希望用折线图、饼图、柱状图等可视化方式展示结论

## 目标

完成一次 GC 日志分析时，优先做到这几件事：
1. 先确认输入范围：到底有几个 `gc.log*` 文件，是否是完整滚动集合
2. 抽取关键指标：时间范围、GC 次数、平均/峰值暂停、长尾暂停次数、GC 原因分布、堆回收后占用、Metaspace 变化
3. 给出人能直接读懂的结论，而不是只堆技术指标
4. 对问题项进行明显标注，让用户一眼看到风险点
5. 为架构师补充可落地的 JVM 调优依据，而不只是“建议继续观察”
6. 按用户需要输出：
   - 正式版 HTML 报告
   - 领导简版 Markdown 结论
7. 如果滚动日志不全，要明确标注分析边界，避免把单窗口结论写成全量结论

## 工作流程

### 第一步：确认输入文件
先找出所有相关 GC 日志文件。

优先检查：
- 用户明确给出的文件路径
- 当前工作目录下的 `gc.log*`
- 常见滚动命名：`gc.log.0.current`、`gc.log.0`、`gc.log.1.current`、`gc.log.1`

确认后要回答：
- 当前实际拿到几个日志文件
- 是否存在日志轮转配置痕迹
- 当前分析是“完整时间窗”还是“部分样本”

如果只拿到一个 `gc.log.0.current`，但日志头里出现了类似：
- `-XX:+UseGCLogFileRotation`
- `-XX:NumberOfGCLogFiles=5`

那就要明确告诉用户：
- JVM 本身开启了滚动日志
- 当前目录下日志不全
- 现有报告只代表当前文件覆盖到的时间窗

### 第二步：识别日志格式并提取核心指标
优先识别日志是否为 JDK8 常见格式，例如：
- `-XX:+PrintGCDetails`
- `-XX:+PrintGCDateStamps`
- `-XX:+PrintGCTimeStamps`
- `-XX:+PrintHeapAtGC`
- CMS / ParNew / G1 相关输出

至少提取这些指标：
- 日志开始时间与结束时间
- 分析时间长度
- GC 总次数
- Full GC 次数
- GC 原因分布
- 平均暂停时间
- 最大暂停时间
- P95 暂停时间
- 超过 200ms、500ms、1s 的暂停次数
- GC 间隔统计（平均/中位/最大/最小）
- GC 后堆占用范围
- 平均回收量
- Metaspace 起始值与结束值
- 高峰时间窗口（例如某个 5 分钟内 GC 次数异常高）

如果日志能支持，还可以补充：
- 老年代占用趋势
- remark / CMS 特殊阶段耗时
- promotion failed / concurrent mode failure 等风险信号
- Survivor 区压力、对象晋升迹象、碎片化迹象

### 第三步：形成判断，不只罗列数字
报告里要有结论性判断。常见判断包括：
- 是否观察到 Full GC 风暴
- 是否属于高频 Young GC
- 是否存在长尾暂停问题
- GC 后堆占用是否长期偏高
- 是否存在明显业务高峰窗口
- 当前更像“对象分配压力大”还是“严重内存故障”

把技术现象翻译成业务影响，例如：
- 秒级暂停可能影响接口 RT 或批处理时效
- GC 后占用高说明存活对象偏多，后续高峰时风险会放大
- 没有 Full GC 是正向信号，但不代表没有性能风险

### 第四步：明确标注问题项
不要把问题埋在长段落里。无论输出 HTML 还是 Markdown，都要把问题项显式列出来。

至少高亮这些内容：
- 风险等级（低 / 中 / 中高 / 高）
- 是否存在 Full GC 风暴
- 是否存在长暂停
- 是否存在老年代高占用
- 是否存在 GC 高峰时间窗
- 是否存在日志不完整导致的结论边界

在 HTML 中优先采用：
- 风险卡片
- 红 / 橙 / 黄的警示块
- “问题项总览”列表
- 明显的标题和标签

在 Markdown 中优先采用：
- `风险等级：中高`
- `重点问题：...`
- `重点时间点：...`
- `调优建议：...`

### 第五步：为架构师提供调优依据
如果用户希望更专业，不能只停留在“现象描述”，还要给出面向架构师的调优思路。

至少从这些角度给出依据：
- 当前 GC 策略是否仍适合业务特征（例如 CMS/ParNew 是否老旧、是否适合当前分配速率）
- 堆划分是否可能不合理（年轻代过小、晋升压力过大、老年代占用偏高）
- 是否更像代码/业务侧对象分配问题，而不是单纯 JVM 参数问题
- 是否需要从批量任务、缓存预热、大对象装载、超大集合、重复序列化等方向排查
- 是否值得评估 G1 或更高版本 JDK

调优建议要尽量分层：
1. **应用侧**：对象创建、批处理方式、SQL 结果集、缓存策略
2. **JVM 参数侧**：新生代比例、晋升阈值、GC 策略适配性
3. **平台侧**：JDK 版本、运行时资源、实例规格、容器内存边界

如果日志不足以支撑某个结论，也要写清楚“当前证据支持到哪一步”，不要过度推断。

### 第六步：输出报告

## HTML 正式报告要求
HTML 适合正式汇报、截图、打印或导出 PDF。优先使用清晰、正式、可读的结构。

从现在开始，默认使用统一专业版式。除非用户明确要求调整，否则不要每次临时换结构。

### 固定 HTML 模板
生成 HTML 报告时，优先稳定输出以下固定章节，顺序尽量保持一致：
1. 报告标题
2. 分析范围与时间窗
3. 执行摘要
4. 风险等级 / 总体结论
5. 问题项总览
6. 关键指标总览
7. 图表总览
8. 主要发现
9. 架构师调优依据
10. 业务影响判断
11. 高峰时间窗口与最长暂停事件
12. 建议动作
13. 数据完整性说明 / 滚动日志合并状态
14. 运行环境与 JVM 参数摘录

### HTML 模板字段要求
每次生成时，都尽量把下列字段填完整：
- 标题：`JVM GC分析正式报告`
- 分析对象：文件名或日志集合名称
- 分析时间窗：开始时间 ~ 结束时间
- 总体结论：稳定、可运行、有风险、需立即关注等
- 风险等级：低 / 中 / 中高 / 高
- 数据完整性：完整 / 部分样本 / 待补日志
- 关键问题：2~5 条
- 关键指标：GC 总次数、平均暂停、最大暂停、P95、长暂停次数、GC 后堆占用、Metaspace 变化
- 调优依据：应用侧 / JVM 参数侧 / 平台侧
- 数据缺口：是否缺少其他滚动日志

### HTML 首屏模板
HTML 首屏必须尽量稳定包含以下信息：
- 报告标题
- 分析时间窗
- 一句话总体结论
- 风险等级
- 数据完整性说明
- 2~4 个高层关键指标卡片
- 一段简短的重要说明（例如“当前仅覆盖单个滚动文件”）

### HTML 视觉模板要求
- 采用正式、浅色、适合打印的风格
- 使用统一的卡片、表格、警示块、章节标题层级
- 问题项使用统一的高亮方式，不要每次换颜色逻辑
- 风险提示优先使用红 / 橙 / 黄三类提示块
- 页面看起来要像正式分析报告，而不是临时拼接的网页
- 结果要能独立打开，不依赖外部资源

写 HTML 时注意：
- 风格适合领导阅读，不要过于“监控大盘化”或过黑过花
- 首屏应出现结论、风险和范围说明
- 技术细节往后放
- 结果要能独立打开，不依赖外部资源
- 问题项要显眼，不能藏在正文里
- 如果用户要求更专业，页面应显得像正式分析报告，而不是普通网页摘要

## 图表展示要求
如果能稳定生成图表，优先在 HTML 中加入图形展示，因为图表能让问题更直观。

优先考虑这些图：
1. **暂停时间折线图**：展示每次 GC 停顿时间随时间变化
2. **GC 次数时间分布图**：按小时或按时间窗展示 GC 密度
3. **GC 原因饼图**：展示 Allocation Failure、Full GC、GCLocker 等占比
4. **GC 后堆占用趋势图**：展示回收后堆占用是否长期偏高
5. **长暂停事件柱状图**：展示 Top N 慢 GC 事件

图表原则：
- 图表要服务于结论，不要为了好看而堆图
- 至少保证 2~4 张最有价值的图
- 如果数据不足，宁可少图，也不要画误导性的图
- 如果环境限制，优先生成纯 HTML 可嵌入图，例如 SVG、Canvas 或内联脚本图表
- 若无法稳定生成图表，也要在报告中说明原因，而不是默默省略

### Markdown 简版结论要求
Markdown 适合粘贴到 Word、邮件或 IM。

从现在开始，默认使用统一专业版式。除非用户明确要求更短或更自由，否则不要随意更换结构。

### 固定 Markdown 模板
生成 Markdown 时，优先稳定输出以下章节：
1. 标题
2. 分析范围
3. 结论摘要
4. 风险等级与问题项
5. 关键观察
6. 架构师调优依据
7. 建议动作
8. 数据缺口 / 补充说明

### Markdown 固定写法要求
优先使用如下口径：
- `风险等级：中高`
- `总体结论：...`
- `重点问题：...`
- `重点时间点：...`
- `调优依据：应用侧 / JVM 参数侧 / 平台侧`
- `数据完整性：...`

如果信息足够，建议每次都覆盖：
- 1 句总体结论
- 3~5 条结论摘要
- 3~5 条关键观察
- 2~4 条调优建议
- 1 条数据边界说明

Markdown 要求：
- 尽量控制在 1 页左右
- 先说结论，再说数字
- 使用领导和架构师都能快速理解的话术
- 不要把局部样本说成全量结论
- 要有单独的问题项和调优依据部分
- 与 HTML 保持同一结论口径，不要两份报告说法不一致

## 多滚动日志处理
如果发现多个 `gc.log.*` 文件：
1. 先确认哪些是同一实例、同一时间序列
2. 按时间顺序合并分析
3. 重新计算整体统计口径
4. 在报告中明确说明这是“完整滚动日志合并分析”还是“当前已发现文件的合并分析”

如果没有多个日志文件：
- 不要假装做了完整合并
- 要明确写出“待补充其余滚动日志后可更新完整报告”

## 输出时的写作原则
- 先结论，后证据
- 先业务影响，后 JVM 细节
- 先问题项，后展开说明
- 不夸大，不模糊
- 对不完整的数据范围必须明确标注
- 对调优建议要分层、有依据、可执行
- 如果用户没指定输出文件名，优先使用：
  - `gc_report.html`
  - `gc_summary.md`

## 默认交付物
在用户没有特别限制时，优先交付：
- 1 份 HTML 正式报告
- 1 份 Markdown 简版结论

如果用户明确要求更专业或适合汇报，默认要补充：
- 问题项显著标注
- 架构师调优依据
- 折线图 / 饼图 / 柱状图等图表展示
- 使用统一固定输出模板，不临时改变版式

## 模板一致性要求
这是一个强调稳定交付体验的 skill。除非用户明确要求改版，否则每次生成报告时都应尽量保持：
- 相同的章节顺序
- 相同的标题风格
- 相同的问题项展示位置
- 相同的风险等级表达方式
- 相同的 HTML / Markdown 结论口径

如果因为数据不足导致某个章节无法完整填写：
- 保留该章节
- 写明“当前数据不足，暂无法得出可靠结论”
- 不要直接删掉章节导致版式漂移

## 示例

### 示例 1
用户：`读取这个 gc.log.0.current，帮我生成一份网页报告，要专业一点，问题项标红。`

应做：
- 读取日志
- 提取核心指标
- 生成带问题项高亮的 `gc_report.html`
- 补充风险等级和结论
- 明确说明当前是不是完整滚动分析

### 示例 2
用户：`帮我看看这些 gc.log.0 gc.log.1 gc.log.2，整理一份给领导和架构师都能看的结论，最好带图。`

应做：
- 识别多文件
- 合并分析
- 生成正式汇报口径
- 加入图表
- 输出 HTML 和 Markdown
- 给出调优依据

### 示例 3
用户：`JVM 最近有点卡，目录里有 gc 日志，你帮我判断是不是 Full GC 问题，并给点调优建议。`

应做：
- 搜索 `gc.log*`
- 判断是否存在 Full GC / 长暂停 / Young GC 高频
- 给出问题性质判断
- 说明调优是更偏应用侧还是 JVM 参数侧
- 视情况补充简版结论

## 失败和边界处理
- 如果日志文件不在当前目录，也不要猜路径，先根据用户提供路径或实际搜索结果处理
- 如果日志太大，分段读取或写解析脚本，不要一次性强读整个文件
- 如果日志格式不完整或无法可靠解析，要明确告诉用户哪里不足
- 如果只拿到单个滚动文件，不要声称完成了完整历史分析
- 如果图表数据不足或环境不适合生成图表，要明确告诉用户，而不是悄悄跳过

## 交付时应主动说明
交付结果时，简要说明：
- 生成了哪些文件
- 当前分析覆盖哪些日志
- 是否缺少其他滚动日志
- 结论里最重要的 3~5 个点
- 哪些问题项被重点标注
- 哪些建议可以作为架构师调优依据