Skip to content

promtop render: -format summary for AI agents and scripts - #7

Merged
igorrius merged 1 commit into
mainfrom
summary-format
Oct 29, 2026
Merged

igorrius merged 1 commit into
mainfrom
summary-format

Conversation

@igorrius

Copy link
Copy Markdown
Owner

What

promtop render -format summary: a compact JSON document (promtop.summary/v1) that an agent or a script reads instead of the raw /metrics exposition or the web dashboard's -format json.

  • Numbers are in base units, with unit next to them. Labels are objects, and labels shared by every series move up to the metric.
  • Every series gets last/avg/min/max/trend/change over the sampled window. Histograms and summaries also get rate, mean and quantiles. Usage metrics get used, limit and a used ratio.
  • notable is a ranked shortlist with these reasons: down, near_limit (≥90%), errors (5xx with their share of the traffic), expires_soon (<7 days), flapped (also statesets), changed (restart or deploy), rising/falling.
  • Flags: -notable prints only that list, -list prints names, types, units and series counts from one scrape, -top n sets the series per metric.

Noise control

  • Trend notes compare the first and last third of the window. Event counters must move beyond Poisson noise. Everything else must move more than it wobbles within the thirds (Welch, 3σ).
  • Quantile trends need 20 observations per third. A histogram's quantiles from before its first rate describe its whole lifetime, so they are not used.
  • GC heap gauges get no trend notes: they climb until each collection.
  • share is taken before -l. Selecting -l 'code=~5..' used to make it 100%.

Sizes on the demo

bytes
raw /metrics 12 188
-format json 14 479
summary ~11 500
summary -list 4 240
summary -notable ~600

Skill

skills/analyzing-metrics-with-promtop is an Agent Skill. Its SKILL.md covers the workflow and common mistakes, and reference.md documents the schema. I tested it with a fresh-context agent on the demo, asking "what's wrong with :8080 and how bad is latency". The agent used only summary and found the full disk, the 5xx, the flapping kafka and the slow search. Its feedback is folded in: stateset flaps, -l scope, share, and used_ratio for *_avail_*.

README has a new "For AI agents and scripts" section. ROADMAP gains -points and an MCP server on top of the summary.

Tests

internal/summary has tests for trends against counting noise, sawtooth gauges, GC heaps, errors and share, health flags and statesets, usage inversion, unit scaling, lifetime histogram points, timestamps, top/omitted, group expansion, and the list/notable shapes. internal/cli checks the format end to end and the flag errors. make test and golangci-lint pass.

🤖 Generated with Claude Code

https://claude.ai/code/session_01US3HyE2LFapBHwkSQRKHsv

A compact, versioned JSON document (promtop.summary/v1) to read instead
of the raw exposition: numbers in base units, labels as objects,
last/avg/min/max/trend of every series over the sampled window, and a
ranked "notable" list: health flags down or flapping, usage at 90%, 5xx
counters with their share of traffic, deadlines under 7 days, moved
timestamps, and changes of 50% between the window's thirds that stand
out of the noise (Poisson for event counters, Welch otherwise; GC heaps
are left out). Histogram quantiles before the first rate describe the
whole lifetime and are not used for trends.

-list prints names, types, units and series counts from one scrape,
-notable only the notable list, -top limits series per metric. The
error share is taken before -l, so selecting 5xx series does not make
it 100%.

skills/analyzing-metrics-with-promtop is an Agent Skill that teaches the
workflow and documents the schema.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01US3HyE2LFapBHwkSQRKHsv
@igorrius igorrius self-assigned this Oct 29, 2026
@igorrius
igorrius merged commit 807baf4 into main Oct 29, 2026
5 checks passed
@igorrius
igorrius deleted the summary-format branch October 29, 2026 15:44
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant