top for Prometheus metrics. Point it at a service's /metrics endpoint and get a live terminal
dashboard — no Prometheus server, no Grafana, no config. Every metric gets a widget chosen from its
type, name and values, so any exporter works: your service, node_exporter, blackbox, kube-state-metrics.
promtop 8080 # http://localhost:8080/metrics
promtop db-1:9187 # http://db-1:9187/metrics
promtop https://svc.example/internal/metrics -H "Authorization: Bearer $TOKEN"
promtop ./dump.prom # an exposition saved to a file![]() |
![]() |
The bundled demo (go run ./examples/demo): enter opens a full-size chart with every series,
histograms show their bucket distribution.
promtop -web 8080Serves the same dashboard as a web page on a free localhost port and opens it in the browser:
cards with charts, hover values and drag-to-zoom in the details, a filter with metric-name
completion, and light or dark theme following the system. The URL keeps the filter and the open
metric (#filter=http&metric=…), so a link reopens the same view. The page only answers to
localhost; -web-addr 0.0.0.0:9999 exposes it to the network on purpose. $BROWSER picks the
browser (BROWSER=true just prints the URL).
From the terminal UI, w starts the same page on the side and opens it; the footer shows its
URL. It is fed by the terminal's scrapes, so it follows its interval and pause, and its history
starts at the press.
The web dashboard is also a Go package: register it next to /metrics and the service shows its
own metrics in the browser while it runs — handy when you are writing the metrics and want to see
them right away, without a Prometheus or OpenTelemetry stack.
go get github.com/igorrius/promtop/dashmux.Handle("/metrics", promhttp.Handler())
metrics := promhttp.HandlerFor(prometheus.DefaultGatherer, promhttp.HandlerOpts{})
mux.Handle("/webmetrics/", dash.New(metrics, dash.Title("orders-svc"))) // http://localhost:8080/webmetrics/The dashboard calls the metrics handler in-process every interval: no network, no port, no
second process. Anything that serves the Prometheus text format works — client_golang,
OpenTelemetry's Prometheus exporter, VictoriaMetrics/metrics. Give it a handler that does not
count its own calls (HandlerFor without HandlerOpts.Registry, as above): promhttp.Handler()
does, and every poll would show up in promhttp_metric_handler_requests_total for your real
scrapers. The requests carry User-Agent: promtop-dash/<version> if your middleware wants to
skip them. It mounts under any path; /webmetrics redirects to /webmetrics/.
Who gets to see it:
dash.Allow(…) |
Admits | Notes |
|---|---|---|
dash.Localhost (default) |
loopback clients naming a loopback host | Works on a dev machine and through kubectl port-forward; ingress and other pods get 403. A reverse-proxy sidecar on localhost looks local too. |
dash.PrivateNetwork |
loopback and private addresses (10/8, 172.16/12, 192.168/16, fc00::/7) | For Docker, docker-compose, WSL2 and local VMs, where the host's browser arrives from a bridge address. In Kubernetes it opens the dashboard to the whole cluster network. |
dash.Anyone |
everyone | |
your own func(*http.Request) bool |
what it says | Compose with the above, e.g. dash.Localhost(r) || vpn.Contains(addr). |
For a login, wrap the handler in your own auth middleware and let it in with dash.Allow(dash.Anyone):
the page and its event stream are plain same-origin requests, so cookies and basic auth reach it,
custom headers do not. The dashboard shows the same data as /metrics next to it. Turning it on per environment is up to
the service, e.g.:
if os.Getenv("DEBUG_DASH") != "" {
mux.Handle("/webmetrics/", dash.New(metrics))
}Options: dash.Interval (default 2s), dash.History (samples kept per series, default 300),
dash.Filter (initial filter regex; one in the page URL wins), dash.Title (page header, default
"this process"). The dashboard lives as long as the process, like /metrics. Close stops polling
and ends open browser streams; hook it to graceful shutdown, otherwise Shutdown waits for an open
tab until its context expires:
d := dash.New(metrics)
mux.Handle("/webmetrics/", d)
srv.RegisterOnShutdown(func() { _ = d.Close() })Do not defer d.Close() in a function that only builds the router: the dashboard would be closed
before the first request and answer 503. The package needs Go 1.27.3 or later. A runnable service
with client_golang is in examples/embedded (make embedded).
Render draws the same history without a browser: a PNG to send to a chat, or the
summary document for a model, with no network and no /metrics listening.
A bot can answer "show me the metrics" this way:
var png bytes.Buffer
err := d.Render(ctx, &png, dash.RenderOptions{Format: dash.FormatPNG, Metrics: []string{"orders_*"}})
// FormatSummary with Notable: true gives a model what stands out, in a few hundred bytesMetrics takes name globs, Sections keeps whole sections by key or by a word of their title
("runtime" is the Go runtime section), and ShowAll adds what the dashboard hides by default
(idle metrics, runtime noise), as promtop render -a. d.Sections(ctx) lists the sections there
are, for a bot's command hints.
promtop render reads the metrics once and draws them into a file — PNG or SVG to send to a
Telegram chat or attach to a report, JSON for a bot that wants the numbers, or text. A pipeline or
an AI agent scrapes, looks at the data and sends a picture people can read at a glance.
promtop render -o dash.png 9100 # the whole dashboard
promtop render -m node_load1 -for 1m -o load.svg 9100 # one metric: its detail chart
promtop render -m 'battery_*' -m 'inverter_*' -title Inverter -o - 192.168.1.50:9100 \
| curl -sF chat_id="$CHAT" -F photo=@- "https://api.telegram.org/bot$TOKEN/sendPhoto"
promtop render -m 'battery_*' -format json 192.168.1.50:9100 # the data behind the pictureWhat is drawn. -m glob (repeatable) and -f regex select metrics, -l selects series with
Prometheus-style label matchers (mount=/data, sensor=~kitchen.*, dev!=lo). With one metric
selected you get its detail view — big chart, bucket distribution, every series — otherwise the
grid; -view grid|detail forces either.
History. A single read has no history: promtop scrapes twice, -i apart, so rates have a
value, and -for 1m samples longer before drawing. For hours or days without a Prometheus server,
let cron collect samples into a small state file and draw from it:
# crontab: a sample every 5 minutes, the last 300 kept (25 hours)
*/5 * * * * promtop record -state ~/.cache/inverter.state -m 'battery_*' 192.168.1.50:9100
# whenever you want the picture
promtop render -state ~/.cache/inverter.state -m 'battery_*' -o battery.png 192.168.1.50:9100render -state adds its own scrape to the file (one that comes right after the cron run replaces
the cron sample, so rates do not cover a few seconds); -offline draws the file without scraping.
The file stores only the selected metrics, so select the limit of a usage bar too
(-m 'node_filesystem_*', not just *_avail_bytes).
| Flag | Meaning |
|---|---|
-o file |
output, - for stdout (the default); the extension picks the format |
-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 |
-state file, -keep n, -offline |
draw a history file (and add to it) |
-title t, -theme dark|light |
header title, colours |
-width n, -height n, -scale x |
width in cells (default 90: two columns), detail chart rows, pixel scale (default 2) |
-style s |
picture style; terminal for now — the same panels as the terminal UI |
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.
-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.
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{"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 and the
runtime's allocation and GC counts are left out) —
the model does the interpreting.
skills/analyzing-metrics-with-promtop is an
Agent Skill that teaches an agent this workflow and the fields
(reference.md there documents the schema). For Claude Code:
cp -r skills/analyzing-metrics-with-promtop ~/.claude/skills/Linux, macOS, FreeBSD:
curl -fsSL https://raw.githubusercontent.com/igorrius/promtop/main/scripts/install.sh | shWindows (PowerShell):
irm https://raw.githubusercontent.com/igorrius/promtop/main/scripts/install.ps1 | iexTo update, run promtop update, or the same command again: it does nothing if the latest
release is already there. promtop update updates the binary you ran, wherever it is, and
PROMTOP_VERSION works with it too. On Windows the running promtop.exe is renamed to
promtop.exe.old to make way for the new one, and the next update removes that file. A copy
from a Linux package is refused: update it with the package manager.
The scripts verify the download against the release's checksums.txt, need no root or
administrator rights, and leave the old binary in place if anything fails. An existing promtop
on PATH is replaced where it stands, if that directory is writable. Otherwise the binary goes to
~/.local/bin (/usr/local/bin for root) or %LOCALAPPDATA%\Programs\promtop; the Windows
script adds that directory to your PATH, the shell script tells you if you need to. A copy
installed from a Linux package in /usr/bin is left to the package manager, so update it
with a new package or remove it, or it may keep running instead.
Two environment variables change this:
curl -fsSL https://raw.githubusercontent.com/igorrius/promtop/main/scripts/install.sh |
PROMTOP_VERSION=v0.5.0 PROMTOP_INSTALL_DIR=/opt/bin sh$env:PROMTOP_VERSION = 'v0.5.0'; $env:PROMTOP_INSTALL_DIR = 'C:\Tools'
irm https://raw.githubusercontent.com/igorrius/promtop/main/scripts/install.ps1 | iexWith Go:
go install github.com/igorrius/promtop@latestOr download a ready-made build from Releases: archives for Linux, macOS, Windows and FreeBSD (amd64, arm64, armv7), and Linux packages:
sudo dpkg -i promtop_*_linux_amd64.deb # Debian, Ubuntu
sudo rpm -i promtop_*_linux_amd64.rpm # Fedora, RHEL
sudo apk add --allow-untrusted promtop_*_linux_amd64.apk # Alpine
sudo pacman -U promtop_*_linux_amd64.pkg.tar.zst # Archpromtop is a single static binary; the terminal UI is built on Bubble Tea and Lip Gloss, so it adapts to the terminal's colour support and light or dark background and works on Linux, macOS, BSD and Windows alike.
| Metric | Widget |
|---|---|
counter |
per-second rate with sparkline; Σ of all series in the title |
counter named *_bytes_total |
throughput, KiB/s |
counter named *_seconds_total |
utilisation in % (e.g. process_cpu_seconds_total → CPU %) |
gauge |
current value, min/max over the window, sparkline |
histogram |
p50/p90/p99 computed from bucket deltas between scrapes, rate, average; bucket distribution in details |
summary |
client-side quantiles, rate, average |
| gauge with a sibling limit | usage bar: open/used/allocated vs max/limit/size, avail/free vs size/total (shown as used), MemFree vs MemTotal; matched per series by labels (node_filesystem_avail_bytes per mount point) |
0/1 gauge named up, *_up, *_success, *_ready, *_healthy, … ; stateset |
state chips, problems first; history strip in details |
*_info, *_build_info, *_labels, info |
label table |
gauge holding a unix time and named *time*, *timestamp*, *last*, *expiry*, … |
age / uptime / time left (seconds or milliseconds) |
untyped *_total |
treated as a counter |
Units come from metric-name suffixes (_bytes, _seconds, _milliseconds, _ratio, _percent,
_celsius, _bits, …) or an OpenMetrics # UNIT line.
Layout:
- Metrics are grouped into sections by name prefix (
http_,db_, your namespace…; dots and colons separate tokens too). Crowded prefixes are split further —node · memory,node · zfs · arc— and small leftovers stay in the parent section. - In a crowded section, single-series gauges and counters with the same unit are packed into one
group panel with a row per metric, so dozens of
node_memory_*_bytestake one panel. go_,process_andpromhttp_runtime sections go last. Well-known runtime metrics are ordered by usefulness — bothclient_golangcollectors (go_goroutines,go_memstats_*) and OpenTelemetry runtime semantic conventions (go_goroutine_count,go_memory_used_bytes).- Hidden until you press
a: metrics that stayed at zero for the whole window, limits already shown in a usage panel, and Go runtime internals (most ofgo_memstats_*,promhttp_*). - Labels shared by every series of a metric, and OpenTelemetry
otel_scope_*labels, are hidden. Multi-series rows list the most distinguishing label first. target_info(OpenTelemetry resource) is shown in the header as the service name.
| Key | Action |
|---|---|
←↑↓→ / hjkl |
move between panels |
[ / ] |
previous / next section |
enter |
details: large chart, every series, buckets |
↑↓ (details) |
choose a series |
←→ / tab (details) |
choose a line (p99, p50, rate, avg, …) |
/ |
filter by regex, tab completes a metric name (c clears) |
a |
show all metrics / curated |
p, space |
pause |
+ / - |
longer / shorter scrape interval |
w |
open the web dashboard (started on first press) |
? |
help |
esc, q |
back / quit |
The mouse works too: click a panel to select it, click it again for details, scroll with the wheel, right-click to go back.
-i duration scrape interval (default 2s)
-H "Name: value" extra request header, repeatable
-f regex only show matching metrics
-a show all metrics, including runtime noise
-history n samples kept per series (default 300)
-timeout d scrape timeout (default: interval, at most 10s)
-once scrape twice, print one frame and exit (CI, logs, screenshots)
-width n width for -once
-no-color disable colours (NO_COLOR is honoured too)
-web serve the dashboard over HTTP and open it in the browser
-web-addr addr listen address for -web and the w key (default 127.0.0.1:0, a free local port)
-version print the version and exit (also: promtop version)
promtop render -h and promtop record -h list the flags of the snapshot commands. The version
is also on the help screen (?) and next to the name on the web page. A release build carries
its tag; go install …@v0.3.0 the module version; a local build the git tag or commit it was
built from (0.3.0+dirty with uncommitted changes).
go run ./examples/demo & # synthetic metrics of every type on :8080
go run . 8080- Rates and histogram quantiles need two scrapes; the first frame shows lifetime values.
- Histogram quantiles use the same linear interpolation as PromQL
histogram_quantile. - The text exposition format (
text/plain; version=0.0.4) is requested; OpenMetrics suffixes (_total,_created,# EOF) are understood as well.
make test # vet + race tests, including the examples/embedded module
make lint # golangci-lint (.golangci.yml)
make snapshot # every release archive and package in dist/, nothing published
make screenshots # docs/*.png and docs/promtop.gif from the demo (needs Chrome and ffmpeg)Releases are built by GoReleaser in CI: push a v* tag and the release with all archives,
packages and checksums appears on GitHub. Every CI run also uploads a snapshot build as an artifact.
To write the notes by hand, publish the release in the GitHub UI with a new v* tag: the tag
starts the same job, which finds the release by its tag, keeps the notes and adds the files.
Two things break it: a release left as a draft (GoReleaser looks releases up by tag, and drafts
have none yet, so it creates a second one) and immutable releases, which accept no files once
published.
What comes next is in ROADMAP.md.
MIT





