Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 41 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -142,7 +142,7 @@ The file stores only the selected metrics, so select the limit of a usage bar to
| Flag | Meaning |
|------|---------|
| `-o file` | output, `-` for stdout (the default); the extension picks the format |
| `-format f` | `png`, `svg`, `json`, `txt` or `ansi` |
| `-format f` | `png`, `svg`, `json`, `summary`, `txt` or `ansi` |
| `-m glob`, `-f regex`, `-l matcher` | select metrics and series |
| `-view v` | `auto` (details for one metric), `grid` or `detail` |
| `-for d`, `-i d` | sample for `d`, every `-i` |
Expand All @@ -154,6 +154,46 @@ The file stores only the selected metrics, so select the limit of a usage bar to
Images are drawn in pure Go with an embedded DejaVu Sans Mono font; box drawing, bars and braille
charts are geometry, so they join up at any scale. No browser, no server.

## For AI agents and scripts

`-format summary` is the JSON to give a model or a script instead of the raw exposition: one line,
numbers in base units, labels as objects, `last/avg/min/max/trend` of every series over the
sampled window, and a ranked `notable` list of what is down, near a limit, answering 5xx, about to
expire, restarted, or moving. The layout is versioned (`"schema": "promtop.summary/v1"`) and does
not change with the web page, which is what `-format json` follows.

```sh
promtop render -format summary -notable -for 1m 9100 # what is wrong, in a few hundred bytes
promtop render -format summary -list 9100 # which metrics there are, no values
promtop render -format summary -for 1m -m 'http_*' -l 'code=~5..' 9100 # dig into one thing
```

```json
{"schema":"promtop.summary/v1","source":"http://localhost:9100/metrics",
"window":{"from":"2026-10-29T14:40:49Z","to":"2026-10-29T14:41:49Z","samples":31,"interval_s":2},
"totals":{"metrics":30,"series":58,"shown":26,"hidden":4},
"notable":[
{"metric":"demo_dependency_up","labels":{"dependency":"kafka"},"reason":"down","changes":2},
{"metric":"demo_disk_avail_bytes","labels":{"mount":"/var/lib/demo"},"value":"used_ratio","reason":"near_limit","last":1},
{"metric":"demo_http_requests_total","value":"rate","reason":"errors","last":0.5,"share":0.0076}]}
```

`-top n` keeps that many series per metric (5 by default, `0` for all), `-for` is what gives
trends (three samples or more), and `-state` with `-offline` reads the history `promtop record`
collected, so a cron job can ask a model about the last day. The detection is deterministic and
small — health flags, usage at 90%, 5xx counters, deadlines under 7 days, timestamps that moved,
and changes of 50% between the first and last third of the window that stand out of the noise
(Poisson for event counters, the spread of the samples otherwise; growing GC heaps are left out) —
the model does the interpreting.

[`skills/analyzing-metrics-with-promtop`](skills/analyzing-metrics-with-promtop) is an
[Agent Skill](https://agentskills.io) that teaches an agent this workflow and the fields
(`reference.md` there documents the schema). For Claude Code:

```sh
cp -r skills/analyzing-metrics-with-promtop ~/.claude/skills/
```

## Install

```sh
Expand Down
5 changes: 5 additions & 0 deletions ROADMAP.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,11 @@ off. Nothing here is promised; issues and pull requests are welcome.
images show boxes where the terminal shows the text.
- **Safe concurrent `record`.** Two writers at the same instant can lose one sample; a lock file
would make it exact.
- **Agent summary: raw points.** A `-points` switch for `-format summary` that adds each series'
samples with timestamps, for questions the window statistics do not answer.
- **An MCP server** (`promtop mcp`) over the summary document, mainly to reach the history of a
running terminal or web session and to hand multimodal models the PNG of a chart; agents with a
shell already get everything else from `render -format summary`.
- PDF output, and a size hint for chat apps (Telegram re-encodes photos above 1280 px).

## Dashboard layout
Expand Down
33 changes: 33 additions & 0 deletions internal/cli/cli_test.go
Original file line number Diff line number Diff line change
@@ -1,9 +1,11 @@
package cli

import (
"encoding/json"
"image/png"
"os"
"path/filepath"
"strings"
"testing"

"github.com/igorrius/promtop/internal/history"
Expand Down Expand Up @@ -34,13 +36,44 @@ func TestRenderCommand(t *testing.T) {
{"-offline", fixture},
{"-view", "pie", "-o", filepath.Join(dir, "x.png"), fixture},
{"-l", "broken", fixture},
{"-list", "-o", filepath.Join(dir, "x.png"), fixture},
{"-format", "summary", "-list", "-notable", fixture},
} {
if code := runRender(args); code != 2 {
t.Errorf("render %v: exit %d, want 2", args, code)
}
}
}

func TestRenderSummary(t *testing.T) {
out := filepath.Join(t.TempDir(), "summary.json")
if code := runRender([]string{"-format", "summary", "-m", "go_*", "-o", out, fixture}); code != 0 {
t.Fatalf("exit %d", code)
}
b, err := os.ReadFile(out)
if err != nil {
t.Fatal(err)
}
var doc struct {
Schema string `json:"schema"`
Notable []json.RawMessage `json:"notable"`
Metrics []struct {
Name string `json:"name"`
} `json:"metrics"`
}
if err := json.Unmarshal(b, &doc); err != nil {
t.Fatalf("%v: %s", err, b)
}
if doc.Schema != "promtop.summary/v1" || doc.Notable == nil || len(doc.Metrics) == 0 {
t.Errorf("summary = %s", b)
}
for _, m := range doc.Metrics {
if !strings.HasPrefix(m.Name, "go_") {
t.Errorf("unselected metric %s", m.Name)
}
}
}

func TestRecordCommand(t *testing.T) {
state := filepath.Join(t.TempDir(), "state")
if code := runRecord([]string{fixture}); code != 2 {
Expand Down
94 changes: 70 additions & 24 deletions internal/cli/render.go
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@ import (
"github.com/igorrius/promtop/internal/render"
"github.com/igorrius/promtop/internal/scrape"
"github.com/igorrius/promtop/internal/store"
"github.com/igorrius/promtop/internal/summary"
"github.com/igorrius/promtop/internal/ui"
"github.com/igorrius/promtop/internal/view"
)
Expand All @@ -34,6 +35,13 @@ Examples:
promtop render -m node_load1 -for 1m -o load.svg 9100 one metric: a detail chart
promtop render -m 'temp_*' -state ~/.cache/temp.state -o temp.png sensors:9100
promtop render -format json -m 'battery_*' 9100 the data, for bots
promtop render -format summary -for 1m 9100 numbers and what changed, for agents
promtop render -format summary -list 9100 which metrics there are

-format summary is a compact, versioned JSON document for AI agents and
scripts (schema promtop.summary/v1): values in base units, labels as
objects, last/avg/min/max/trend over the sampled window, and a "notable"
list of series that are down, near a limit, erroring or moving.

Without -state or -for promtop scrapes twice, -i apart, so rates have a value
but charts have only two points; -for samples longer, and -state draws the
Expand Down Expand Up @@ -65,7 +73,7 @@ func runRender(args []string) int {
sel := addSelectFlags(fs)
var (
out = fs.String("o", "-", "output file, - for stdout")
format = fs.String("format", "", "png, svg, json, txt or ansi (default: from the -o extension, else png)")
format = fs.String("format", "", "png, svg, json, summary, txt or ansi (default: from the -o extension, else png)")
style = fs.String("style", "terminal", "picture style: "+strings.Join(render.StyleNames(), ", "))
viewMode = fs.String("view", "auto", "grid, detail, or auto: details when one metric is selected")
all = fs.Bool("a", false, "include metrics hidden in curated mode (idle, merged limits, runtime internals)")
Expand All @@ -78,6 +86,9 @@ func runRender(args []string) int {
width = fs.Int("width", 0, "width in cells (default: 90 for a grid, two columns; 100 for details)")
height = fs.Int("height", 12, "chart height in cells of each detail view")
scale = fs.Float64("scale", 2, "image scale: 1 means a 15px font")
top = fs.Int("top", 5, "-format summary: series per metric, 0 for all")
list = fs.Bool("list", false, "-format summary: only names, types, units and series counts")
notable = fs.Bool("notable", false, "-format summary: only the notable list")
)
fs.Usage = func() {
_, _ = fmt.Fprint(fs.Output(), renderUsage)
Expand All @@ -95,10 +106,24 @@ func runRender(args []string) int {
}
}
switch f {
case render.PNG, render.SVG, render.JSON, render.Text, render.ANSI:
case render.PNG, render.SVG, render.JSON, render.Text, render.ANSI, formatSummary:
default:
return usageErr(fmt.Errorf("unknown format %q", *format))
}
if f != formatSummary {
var only error
fs.Visit(func(fl *flag.Flag) {
if fl.Name == "top" || fl.Name == "list" || fl.Name == "notable" {
only = fmt.Errorf("-%s needs -format summary", fl.Name)
}
})
if only != nil {
return usageErr(only)
}
}
if *list && *notable {
return usageErr(errors.New("-list and -notable do not combine"))
}
if *out == "-" && f.Binary() && term.IsTerminal(os.Stdout.Fd()) {
return usageErr(errors.New("refusing to write PNG to a terminal; use -o file.png or a pipe"))
}
Expand All @@ -125,42 +150,46 @@ func runRender(args []string) int {
defer stop()
st := store.New(*keep)
interval := *sf.interval
var scrapes []history.Scrape
// raw is the history before the label matchers: what the summary's error
// share is taken from, so -l 'code=~5..' does not make it 100%.
var raw []history.Scrape
fresh := 0
if *statePath != "" {
if scrapes, err = history.Load(*statePath); err != nil {
if raw, err = history.Load(*statePath); err != nil {
return fail(err)
}
for i := range scrapes {
if scrapes[i].Families, err = selector.Apply(scrapes[i].Families); err != nil {
return usageErr(err)
}
}
}
if !*offline {
fresh, err := sampleScrapes(ctx, src, interval, *sample, len(scrapes) > 0)
// A list needs names, not rates: one scrape is enough.
got, err := sampleScrapes(ctx, src, interval, *sample, len(raw) > 0 || *list)
switch {
case err != nil && len(scrapes) == 0:
case err != nil && len(raw) == 0:
return fail(err)
case err != nil:
fmt.Fprintf(os.Stderr, "promtop: %v; drawing the stored history\n", err)
}
for _, s := range fresh {
fresh = len(got)
for _, s := range got {
// A history file stores only the selection; a one-off render keeps
// every family, so usage panels still find their limits.
if *statePath != "" {
s.Families, err = keepSelected(s.Families, names, selector)
} else {
s.Families, err = selector.Apply(s.Families)
}
if err != nil {
return usageErr(err)
if s.Families, err = keepSelected(s.Families, names, view.Selector{}); err != nil {
return usageErr(err)
}
}
scrapes = history.Append(scrapes, s)
raw = history.Append(raw, s)
}
if *statePath != "" && len(fresh) > 0 {
if err := history.Save(*statePath, scrapes, *keep); err != nil {
return fail(err)
}
}
scrapes := make([]history.Scrape, len(raw))
for i, s := range raw {
if s.Families, err = selector.Apply(s.Families); err != nil {
return usageErr(err)
}
scrapes[i] = s
}
if *statePath != "" && fresh > 0 {
if err := history.Save(*statePath, scrapes, *keep); err != nil {
return fail(err)
}
}
if len(scrapes) == 0 {
Expand Down Expand Up @@ -219,12 +248,29 @@ func runRender(args []string) int {
defer func() { _ = file.Close() }()
w = file
}
if err := render.Render(w, snap, *style, f, render.Options{Scale: *scale}); err != nil {
if f == formatSummary {
so := summary.Options{
Source: src.String(), From: scrapes[0].At, To: snap.At, Interval: interval, Now: snap.Now,
Top: *top, List: *list, Notable: *notable,
}
if len(selector.Labels) > 0 {
so.Unfiltered = store.New(*keep)
history.Replay(so.Unfiltered, raw)
}
err = summary.Write(w, st, secs, so)
} else {
err = render.Render(w, snap, *style, f, render.Options{Scale: *scale})
}
if err != nil {
return fail(err)
}
return 0
}

// formatSummary is the agent document of package summary; it is not a
// picture of the dashboard, so it lives next to render's formats, not in them.
const formatSummary render.Format = "summary"

func runRecord(args []string) int {
fs := flag.NewFlagSet("promtop record", flag.ContinueOnError)
sf := addSourceFlags(fs, 2*time.Second)
Expand Down
Loading
Loading