Repository navigation
promtop render: -format summary for AI agents and scripts - #7
Merged
Merged
Conversation
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
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
promtop render -format summary: a compact JSON document (promtop.summary/v1) that an agent or a script reads instead of the raw/metricsexposition or the web dashboard's-format json.unitnext to them. Labels are objects, and labels shared by every series move up to the metric.last/avg/min/max/trend/changeover the sampled window. Histograms and summaries also getrate,meanandquantiles. Usage metrics getused,limitand a used ratio.notableis a ranked shortlist with these reasons:down,near_limit(≥90%),errors(5xx with theirshareof the traffic),expires_soon(<7 days),flapped(also statesets),changed(restart or deploy),rising/falling.-notableprints only that list,-listprints names, types, units and series counts from one scrape,-top nsets the series per metric.Noise control
shareis taken before-l. Selecting-l 'code=~5..'used to make it 100%.Sizes on the demo
/metrics-format jsonsummarysummary -listsummary -notableSkill
skills/analyzing-metrics-with-promtopis an Agent Skill. ItsSKILL.mdcovers the workflow and common mistakes, andreference.mddocuments 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 onlysummaryand found the full disk, the 5xx, the flapping kafka and the slow search. Its feedback is folded in: stateset flaps,-lscope,share, andused_ratiofor*_avail_*.README has a new "For AI agents and scripts" section. ROADMAP gains
-pointsand an MCP server on top of the summary.Tests
internal/summaryhas 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/clichecks the format end to end and the flag errors.make testandgolangci-lintpass.🤖 Generated with Claude Code
https://claude.ai/code/session_01US3HyE2LFapBHwkSQRKHsv