# investigating-metric-anomalies

investigating-metric-anomalies turns a PostHog Metrics symptom (rising lag, error spike, falling throughput) into a probable cause backed by logs and traces.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 206 installs · ★ 101 repo stars
- Author: PostHog
- License: not stated · policy=link-only · description only; the file stays with the author
- Source: https://github.com/PostHog/ai-plugin/tree/HEAD/skills/investigating-metric-anomalies/SKILL.md
- Updated: 2026-10-24
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/investigating-metric-anomalies

## What it does

Starts from a symptom in PostHog Metrics and works toward a cause you can defend. The metric name comes first: `metric-names-list` takes a fragment such as `lag` or `error`, and the type it returns decides the lens, since counters only make sense as a rate or increase, gauges as an average, histograms as a quantile.

One call to `characterize-metric-anomaly` with `anomalyFrom` answers three things: how far the value moved, when it started (`onset_time`), and which label values shifted (`top_movers`). A single pod or shard in the movers points at a local fault; everything moving at once points upstream. `query-metrics` then tests those guesses with `filters` and formulas like `errors / requests`, and logs (`query-logs`) plus spans (`query-apm-spans`) get pulled for the same service in a window around `onset_time`.

It runs on a project that already has PostHog Metrics and the PostHog MCP tools wired up. Without them there is nothing to call. Scraped Prometheus series also lag real time by 15–60 seconds, so the newest bucket is not the current value.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add PostHog/ai-plugin --skill investigating-metric-anomalies -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/investigating-metric-anomalies/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/investigating-metric-anomalies/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add PostHog/ai-plugin --skill investigating-metric-anomalies -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/investigating-metric-anomalies/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add PostHog/ai-plugin --skill investigating-metric-anomalies -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/investigating-metric-anomalies/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install PostHog/ai-plugin skills/investigating-metric-anomalies
```

2. **Manually: put the files in place**
- File: `.github/skills/investigating-metric-anomalies/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add PostHog/ai-plugin --skill investigating-metric-anomalies -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/PostHog/ai-plugin --path skills/investigating-metric-anomalies
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/investigating-metric-anomalies/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add PostHog/ai-plugin --skill investigating-metric-anomalies -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/PostHog/ai-plugin/tree/HEAD/skills/investigating-metric-anomalies/SKILL.md

## When to use it
- pin down which metric an alert refers to
- date the onset of a spike from the alert time
- split a single-pod fault from a shared upstream cause
- separate a real error increase from a traffic jump
- tie a metric spike to a process restart in the logs

## Example prompts
- Ingestion lag is climbing since 20:10 — find the metric and show what moved.
- Investigate `logs_rate_limiter_message_lag_seconds` from the alert time and check that service's logs around the onset.
- Error rate on the checkout endpoint is spiking; look at metrics first, then spans and logs for the same window.

## Similar
- [cx-telemetry-querying](https://affpapa.org/en/nevibecode/skills/cx-telemetry-querying.md) — skill · 6300 installs
- [SigNoz MCP Server](https://affpapa.org/en/nevibecode/mcp/signoz-mcp-server.md) — MCP server · ★ 132 repo stars
- [openobserve-skills](https://affpapa.org/en/nevibecode/plugins/openobserve-skills.md) — plugin · ★ 1216 repo stars
- [datadog](https://affpapa.org/en/nevibecode/plugins/datadog.md) — plugin · ★ 20 repo stars
- [investigating-incidents-with-aws-devops-agent](https://affpapa.org/en/nevibecode/skills/investigating-incidents-with-aws-devops-agent.md) — skill · 1600 installs
- [investigate](https://affpapa.org/en/nevibecode/skills/launchdarkly-investigate.md) — skill · 718 installs

From the same set: [posthog/ai-plugin](https://affpapa.org/en/nevibecode/by/posthog/ai-plugin.md) — 82 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
