monitoring-graphs — Claude Code skill: annotated incident graphs
monitoring-graphs — a skill for Claude Code, Codex and Gemini CLI that generates annotated incident graphs in Python. Use it to visualize outages, plot error spikes, or correlate metrics with incident milestones.
Apache-2.0 ★ 151 updated 2026-10-12
/plugin marketplace add gemini-cli-extensions/sre
/plugin install sre-extension@sreWhat monitoring-graphs does
The skill guides you through metric selection, data extraction from Cloud Monitoring, and professional graph creation with timeline annotations (detection, mitigation, resolution). It works across Claude Code, Codex and Gemini CLI.
Inside are Python scripts for draft and final graphs. Draft confirms the data carries a real signal; final adds colour-coded annotations—red for outage, yellow for detection, green for fix. The skill requires Python and Cloud Monitoring access; all timestamps default to UTC.
The skill enforces one rule: never invent numbers. If a full blackout causes the API to return no data points, it fills gaps with zeros through reindexing instead of fabricating values.
What it helps with
- build an outage graph with incident stages for a postmortem
- plot error rate spikes and correlate them with traffic on one chart
- annotate detection and mitigation time windows on the same graph
- extract metrics from Cloud Monitoring and verify the signal is real
- save multiple graph revisions without overwriting previous versions
Example prompts for the agent
- Create an incident graph for our postmortem: outage started 2024-01-15 10:30, detected 10:45, mitigated 11:20, resolved 11:35.
- Plot the service availability with traffic correlation during the March 14 incident.
- Pull metrics from Monitoring, build a draft graph to confirm the signal, then add annotations.
How to install monitoring-graphs
1Plugin marketplace
/plugin marketplace add gemini-cli-extensions/sre/plugin install sre-extension@sreThis installs the whole sre-extension plugin with all its skills
2Skills CLI (Vercel)
npx skills add gemini-cli-extensions/sre --skill monitoring-graphs -a claude-code3Manually: put the files in place
~/.claude/skills/monitoring-graphs/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/monitoring-graphs/
1Skills CLI (Vercel)
npx skills add gemini-cli-extensions/sre --skill monitoring-graphs -a codex2Manually: put the files in place
.agents/skills/monitoring-graphs/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add gemini-cli-extensions/sre --skill monitoring-graphs -a cursor2Manually: put the files in place
.cursor/skills/monitoring-graphs/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install gemini-cli-extensions/sre skills/monitoring-graphs2Manually: put the files in place
.github/skills/monitoring-graphs/SKILL.md1Skills CLI (Vercel)
npx skills add gemini-cli-extensions/sre --skill monitoring-graphs -a gemini-cli2Platform CLI
gemini skills install https://github.com/gemini-cli-extensions/sre --path skills/monitoring-graphsManually: put the files in place
.devin/skills/monitoring-graphs/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about monitoring-graphs
How do I install monitoring-graphs in Claude Code?
In Claude Code, run /plugin marketplace add gemini-cli-extensions/sre, then /plugin install sre-extension@sre, then npx skills add gemini-cli-extensions/sre --skill monitoring-graphs -a claude-code. The skill will be available at ~/.claude/skills/monitoring-graphs/SKILL.md.
What does monitoring-graphs do?
The skill generates annotated incident graphs: it fetches metrics from Cloud Monitoring, builds a draft graph to verify the signal is real, then creates a final graph with colour-coded timeline markers (yellow for detection, red for outage, green for fix).
What do I need to use this skill?
You need Python, access to Cloud Monitoring to pull metrics, and timestamps in UTC. The skill does not fabricate data. If a complete outage causes the API to return no readings, it fills missing time intervals with zeros rather than inventing values.
Source text
SKILL.md · Apache-2.0
---
name: monitoring-graphs
description: 🐉 Skill for generating high-quality, annotated incident graphs for post-mortems using Python. Use this when the user needs to visualize an outage, show error rates, or correlate metrics with incident milestones.
#verbose_description: Expert SRE skill for generating high-quality, annotated incident graphs for post-mortems using Python and Monitoring MCP on Google Cloud. Use this when the user needs to visualize an outage, show error rates, or correlate metrics with incident milestones (start, detection, mitigation, end).
metadata:
author: Riccardo Carlesso
version: 0.0.6
---
# 📈 Monitoring & Incident Graphing Skill 📊
This skill guides the agent through identifying high-signal metrics, extracting data efficiently, and creating professional annotated graphs.
## 🚨 DATA INTEGRITY: NEVER MAKE UP NUMBERS
- **ONLY REAL DATA:** Absolutely **NEVER** fake data, interpolate guesses, or hard-code values (like forcing a firewall block period to exactly 0) just to make a graph look "correct" or align with a narrative.
- **The Data Is The Source Of Truth:** If there is an outage, the raw metrics or the *absence* of metrics must prove it. Show the *real* raw availability.
- **Handling Complete Blackouts:** If a full blackout causes missing data points from the API, do not invent data. Instead, use Pandas `reindex` to fill the missing continuous time intervals with 0s.
## 🚀 Workflow
### 1. Metric Selection & Efficient Extraction 🕵️♀️
- **Standard Time:** Always use **UTC** for all timestamps by default. 🌐
- **Performance Tip:** Cloud Monitoring can be **VERY SLOW** for high-res data. 🐢
- **Execution:**
1. Use Monitoring MCP to find relevant metrics for the incident time window.
2. Download the data as CSV (e.g., `out/incident/metric.csv`) or directly parse JSON.
3. Use a sub-agent (`generalist`) for large datasets to keep the main session history lean.
- **Reference:** See [archetypes.md](references/archetypes.md) for "Apple-to-Apple" strategies and granularity tables.
### 2. Baseline Graph (Draft) 🖼️
- **Rule:** Always generate a raw "Draft" graph first to confirm the data shows a clear signal.
- **Command:**
```bash
uv run ./scripts/plot_archetype.py --csv data.csv --out draft.png --title "Title"
```
- **Verification:** Ensure the graph is not "flat." The X-axis must explicitly show "Time (UTC)" so there is no ambiguity! 🕰️
### 3. Annotated Graph (Final) 🔴
- **Requirement:** Only proceed after the user confirms the draft is "good."
- **Command:**
```bash
# Times are assumed to be UTC unless --timezone is specified
uv run ./scripts/plot_archetype.py \
--csv data.csv \
--out final.png \
--final \
--start "YYYY-MM-DD HH:MM:SS" \
--detect "YYYY-MM-DD HH:MM:SS" \
--mitigate "YYYY-MM-DD HH:MM:SS" \
--end "YYYY-MM-DD HH:MM:SS"
```
- **Styling Guidelines (Annotations):**
- **Red (`#d93025`):** Breakages, outages, faults, or incident start/end. Use different line thicknesses (`linewidth=1` to `3`) or styles (`:`, `--`, `-.`) to denote severity.
- **Yellow (`#f9ab00`):** Human detection or alert triggered.
- **Green (`#1e8e3e`):** Fix, mitigation, or resolution applied.
## 📝 Safeguards & Tips
* **Scaling Lines:** Use `--hmin` and `--hmax` to show Cloud Run/GKE scaling limits (min/max instances).
* **Auto-Coloring:** Blue for `ingress`, Green for `egress` for Network I/O.
* **Timeouts:** Use `timeout 60` for data extraction tool calls to avoid infinite loops. Also prefer MCP calls to Monitoring/Logging (faster) vs `gcloud` commands (slower).
* **Clear Timing:** Ensure that looking at the time variable allows a person to know EXACTLY what that time is.
* For instance, if time is 03:00 ensure the TZ is specified in the X-axis label.
* If the graph only contains HOURS (ie, all happens within a day) and no days, then ensure the day is also written in the X-axis label.
* **Correlation in graphs**: if you need to prove a time-correlation between heterogeneous graphs (eg error logs volume vs increase in traffic) remember:
* **Time is key** - keep a single X-axis with consistent time across the 2+ graphs.
* Example: `assets/sample_correlation_data/improved_incident_graphs.png`
* **Revision and multiple files**. Since images are very succulent, if you create a new image do NOT overwrite the old image, rather add _rev1, _rev2, .. to the file name.
* If an image is proven to be wrong by further investigation, do NOT delete it, rather add it to Trash/ within the original folder, and possibly rename it to why it was wrong in the filename.
## 🐍 Juicy Python Patterns (From Real Investigations)
See `scripts/reference_dual_plot.py` for a complete example of parsing JSON and plotting.
### 1. Handling Missing Data (Reindexing)
```python
# Force 0s for missing data in outages (Pandas)
full_range = pd.date_range(start=df.index.min(), end=df.index.max(), freq='1min')
df = df.reindex(full_range, fill_value=0)
```
### 2. Smoothing "Golden Signals"
```python
# 5min rolling average for smoother 'Golden Signal' look
vol_smooth = grouped['Total'].rolling(5, min_periods=1).mean().fillna(0)
avail_smooth = grouped['Availability'].rolling(5, min_periods=1).mean().fillna(0)
```
### 3. Dual Axes (Availability & Traffic)
```python
fig, (ax1, ax2) = plt.subplots(2, 1, figsize=(15, 10), sharex=True)
ax1.plot(df.index, df.avail, color='#d93025', label='Success Rate') # Top: %
ax1.fill_between(df.index, df.avail, color='#d93025', alpha=0.1)
ax2.plot(df.index, df.vol, color='#1a73e8', label='Traffic') # Bottom: Volume
ax2.fill_between(df.index, df.vol, color='#1a73e8', alpha=0.1)
```
© Riccardo Carlesso · Apache-2.0 · gemini-cli-extensions/sre