askee is a dashboard for Prometheus metrics. It queries a Prometheus-compatible database (Prometheus or VictoriaMetrics) and draws charts in a terminal, in a web browser or as plain text. It is a single Go binary with no dependencies outside the standard library.
askee only reads. It needs a database that already holds your metrics, and it stores nothing of its own.
The CPU temperature page in the terminal, in the carbon theme, drawn with
askee -dump 2. The dashed line is the sensor's limit and the dotted line marks a
reboot. The data is synthetic, served by a fake Prometheus API. The screenshots in
this README use the two default themes: carbon for dark screens and newsprint for
light ones.
your machines your database askee
node_exporter, etc. ──▶ Prometheus / VictoriaMetrics ◀── queries it ──▶ terminal
(expose /metrics) (scrapes and stores) (PromQL from browser
your config) plain text
- An exporter publishes metrics from each machine. node_exporter is the usual one, but any exporter works.
- Prometheus or VictoriaMetrics scrapes and stores them. askee needs the database's query URL. It keeps no data and writes nothing to disk.
- A config file lists the charts. Each chart is a page with one or more PromQL queries. Built-in packs cover node_exporter, so without a config file askee shows every pack: CPU, memory, storage, network and the blocky DNS proxy.
- askee queries the database while someone is looking at a chart. The terminal, the web page and the text output run the same queries from the same config, so a chart shows the same data in each.
A built-in page that needs something the machine lacks, such as ZFS or a temperature sensor, is hidden when its query returns nothing.
askee's charts look like printed charts: one ink on a plain background, monospace type, and the numbers printed beside each chart. The default themes are greyscale. Any dashboard could follow the same rules.
- In the one-ink themes, lines differ by dash pattern (solid, dashed, dotted,
dash-dot, long dash), so charts read in greyscale and for colour-blind readers. The
colour themes are tested for colour blindness against their own background.
askee -themesprints the results. - Each line is labelled at its right-hand end with its name and latest value. There is no legend.
- The y axis runs from the lowest value in the data to the highest.
- A reference value, such as the core count or a sensor's limit, is a labelled dashed line. An event, such as a reboot, is a dotted line.
- The text view prints the latest, minimum, maximum and mean of every series, so readers do not have to estimate values from the line.
- In the terminal, lines are drawn in braille characters (2 × 4 dots each) and bars in eighth-blocks, so charts work over SSH.
- askee refuses a page whose title contains a comma or a dash, whose
infois longer than one sentence, or whosenoteis longer than 50 characters. The error names the page and the rule.
git clone https://github.com/jtrotsky/askee.git
cd askee
go build -o askee .It needs Go 1.27 or later. It builds for FreeBSD, Linux and macOS. It does not
build for Windows, because the terminal view uses stty.
Point askee at your database:
askee -vm http://127.0.0.1:9090 -print system # plain text, then exit
askee -vm http://127.0.0.1:9090 # terminal view
askee -vm http://127.0.0.1:9090 -serve 127.0.0.1:8095 # web dashboardTo choose packs or add your own charts, write a config file, askee.json:
{
"title": "demo",
"vm": "http://127.0.0.1:9090",
"scrape_interval": "15s",
"packs": ["system", "memory"]
}askee looks for $ASKEE_CONFIG, then ./askee.json, then
~/.config/askee/askee.json, then /usr/local/etc/askee/askee.json. Here is
part of -print system from synthetic data, shown as an image because
GitHub's code font has no braille:
The number lines are plain text, so scripts can read them:
kernel latest 12.2 min 4.81 max 24.4 mean 9.62 % (n=289)
apps latest 21.7 min 6.60 max 25.3 mean 15.9 % (n=289)
hottest latest 67.0 min 50.3 max 79.9 mean 58.5 °C (n=289)
| flag | what it does |
|---|---|
-config FILE |
the config file (see above for where askee looks without it) |
-vm URL |
the database URL. Overrides the config's. Also $ASKEE_VM |
-print GROUP |
print one group of charts as text and exit |
-range R |
range for -print: live, 1h, 6h, 24h, 7d, 30d or 90d |
-size WxH |
size of each chart for -print and -dump (default 100x14) |
-dump N |
draw page N once, with colour, and exit. Needs no terminal |
-serve ADDR |
serve the web dashboard on this address |
-page N |
page the terminal view opens on |
-packs |
list the built-in packs |
-themes |
list the themes and whether each passed the colour-blindness check |
Terminal. One chart per screen. Lines are drawn in braille (2 × 4 dots per character)
and bars in eighth-blocks. ←/→ or h/l move between charts, ↑/↓ or k/j change the
range, 1 to 7 pick a range, t changes the theme and q quits. It uses truecolour when
$COLORTERM says the terminal has it, and the nearest xterm-256 colour otherwise.
Web. A grid of charts sized to the window, one group per screen. The page is built into the binary. The browser can ask only for a group and one of the fixed ranges. Every query comes from the config file, so the dashboard runs no query text sent to it. askee rereads the config every 30 seconds and picks up changes without a restart. The database URL and the live sources still need one.
Text. -print draws a group as boxed panels with a numbers line per series, for scripts,
health checks and anything else that reads text.
Each pack works with node_exporter on both Linux and FreeBSD. Where the two name a metric
differently, the query asks for both. A page that needs something a machine lacks, such as ZFS,
swap or a temperature sensor, names it in requires and is left out when the query returns
nothing. On a Linux machine without ZFS, the memory pack shows 3 of its 6 pages.
| pack | pages | charts |
|---|---|---|
system |
4 | CPU busy by kind, CPU temperature, load against the core count, CPU busy by hour of day |
memory |
6 | memory use (FreeBSD or Linux accounting), swap used, swap activity, ZFS cache misses and size |
storage |
3 | fullest filesystems, free space on /, disk traffic |
network |
2 | traffic on physical network cards, traffic by interface |
blocky |
4 | queries, share blocked, answer time and answers by type for the blocky DNS proxy |
A config with no pages of its own and no packs key gets every pack. To replace one pack
chart, give your own page the same id. To drop one, list its id in hide. $node in a query
stands for the config's node_filter, so one database that holds many machines can be charted
one machine at a time:
{
"title": "web1",
"vm": "http://prometheus:9090",
"node_filter": "instance=\"web1:9100\"",
"packs": ["system", "memory", "storage", "network"],
"hide": ["cpu_hour"]
}A page is one chart. Each has an id, a group, a kind, a short title and usually one or
more PromQL expressions:
{"id": "load", "group": "system", "kind": "line", "title": "Load",
"info": "Above 4, the core count, work is queueing.",
"series": [{"expr": "node_load1", "name": "1 min"}, {"expr": "node_load15", "name": "15 min"}],
"refs": [{"value": 4, "label": "4 cores"}]}| kind | draws |
|---|---|
line |
series over time. stack for parts of a whole, split for one panel per series, log for a log scale, lo and hi for a band behind a line, thermal to colour a line by temperature |
days |
one figure per calendar day, as bars or dots, with an optional band for the usual range |
hour |
the mean for each hour of the day over a fixed window (30 days by default) |
clock |
one row per day across a clock face, for when in the day something happens |
instant |
one bar per result of an instant query |
runs |
one bar per run of a job |
capacity |
how full each thing is, as rows of cells |
snapshot |
a section of a Markdown file written by another job |
sizes |
a table of sizes per target and store, as rows of cells |
A page that breaks the writing rules (see Design) is refused. On a live reload the last good config keeps serving.
Each key is listed, with a comment, in the PageCfg type in config.go. The pack
files under packs/ are working examples of line, instant and hour pages.
Nine themes, shared by all three views. Choose one with t, ?theme=sepia in the URL, or
ASKEE_THEME=sepia in the terminal. The default follows the system: newsprint on a light
screen and carbon on a dark one.
Five themes use one ink and tell lines apart by dash pattern, so a chart stays readable in
greyscale and for readers who do not see colour the usual way: newsprint, sepia, carbon,
phosphor and amber. Four use colour. fjord and ember-chalk pass a colour-blindness check
against their own background. chalkboard sits just under it, so its lines are also dashed.
terminal, the plain xterm colours, fails (yellow against green). askee -themes prints each
palette and its result.
The System page in the other seven themes.
ember-chalk, warm grey with ember and teal
fjord, slate and muted blue![]() |
chalkboard, chalk on slate green![]() |
sepia, brown ink on old paper![]() |
phosphor, a green CRT![]() |
amber, an amber CRT![]() |
terminal, the plain xterm colours![]() |
Set live_source to an exporter's /metrics URL and the live range updates once a second.
askee reads the exporter only while someone is watching, keeps the last five minutes in memory
and stores nothing. It computes live charts from a small subset of PromQL (rate, sum, avg,
max, min, label matchers and arithmetic).
go test ./...The tests run against a fake Prometheus API, so they need no database. They render every page
of examples/node-exporter.json at every range and check that
each pack parses, that page ids are unique and that every rate() has a window.
test/perf.mjs times the web page in headless Chrome against a budget.
ascii/ is a separate set of sh and awk scripts for written reports. It draws bars,
sparklines and braille line plots as text, and turns a Markdown subset into one self-contained
HTML file. See ascii/README.md.
MIT. See LICENSE.











