Vercel Triage

/vercel-triage — is prod actually erroring, or is it log noise?

A raw vercel logs dump is almost useless for triage: the same event is emitted many times over, the retention window is short, and 4xx noise drowns the handful of 5xx that are real user-facing failures. Every manual pass re-learns the same workarounds. This skill bakes them in: pull once, dedupe, and surface only the errors that mean something — with counts, so a spike is obvious.

Read-only. It reads logs and reports; it changes no deployment and no config.

When to use this

• "Check the Vercel logs", "is prod down / erroring", "triage production".
• A user report of errors and you need to know if it's real and how widespread.
• A post-deploy health read.

When NOT to use this

• You need history older than ~24h — Vercel runtime logs don't retain it. Use a log drain / observability provider instead, and say so.
• The question is build failures, not runtime — that's vercel inspect / deployment logs, a different surface (see references).

Prerequisites (check first, fail clear)

command -v vercel || echo "install: npm i -g vercel"
vercel whoami            # authed?
[ -f .vercel/project.json ] || echo "run: vercel link"

If any fails, tell the user the one command to fix it and stop — don't guess a project.

Workflow

1. Run the triage script from the linked project root:

   bash "$SKILL_DIR/scripts/triage.sh"           # last window, prod
   bash "$SKILL_DIR/scripts/triage.sh --status 500   # only 5xx"
   

   It resolves the current production deployment, pulls its runtime logs, dedupes identical events, and groups what's left by status and path with counts. Raw output is saved to a temp file it names, so you can grep deeper without re-pulling.

2. Read the summary, not the raw stream. The script prints, most-frequent first: <count> <status> <method> <path> <last-seen>. A single 500 is a blip; the same 500 fifty times on one route is an incident.

3. Filter to real failures. 5xx are the ones that mean the app broke. Treat 4xx as signal only when the user is chasing a specific auth/not-found report — most 401/403/404 are expected. references/reading-logs.md maps common statuses to "act vs ignore" for this stack.

4. For a real 5xx, get the trace. Grep the saved raw file for the path and read the surrounding lines for the stack / error message. Turn that into a one-line root cause, not a paste of the whole trace.

5. Report (see format below). If nothing real surfaced, say "prod clean in the last window" plainly — a quiet result is the product.

The CLI traps (why the script exists)

• Duplicated events — the same log line arrives many times; naive wc -l massively overcounts. The script dedupes on the event signature before it counts anything. Never report a raw line count as an error count.
• Short --until window — large --until values are rejected; the script pulls in a bounded window and says what window it covered.
• ~24h retention — anything older is simply gone from this surface. If the user asks about yesterday-plus, name the limit and point at the drain.
• Only 5xx = user-facing break — 4xx is mostly expected traffic.

Report format

• Verdict: clean / N distinct 5xx / active incident — one line.
• Top errors: the count-ranked table, 5xx first.
• Root cause for each real one: the failing path + the one-line reason from the trace.
• Window & limits: what time range this covered, and that >24h isn't here.

References

• references/reading-logs.md — status-by-status act-vs-ignore, and where build logs / drains live for the questions this surface can't answer.