spinal-tap

Small, fast terminal dashboard for DogStatsD metrics.

spinal-tap listens on UDP, parses DogStatsD packets, and renders selected counters, gauges, and histograms in a ratatui dashboard. It is intended as a lightweight companion for projects using e.g. fast-telemetry: start it, point your export at this, and watch current process behavior without persistence, querying, or a heavyweight metrics stack.

Run

cargo run --release -- config.example.toml

By default, if no config path is passed, spinal-tap looks for spinal-tap.toml. If that file is missing, it starts with defaults and listens on 127.0.0.1:8125.

Runtime changes can be saved back to the startup config path with Ctrl-X then Ctrl-S, or Ctrl-X then s. If the app was started without a config path, this writes spinal-tap.toml.

Config

listen = "127.0.0.1:8125"
history_points = 120
redraw_millis = 250

[[metrics]]
name = "requests"
view = "chart"
kind = "counter"
display = "rate"
unit = "req"

[[metrics]]
name = "queue.depth"
view = "numeric"
kind = "gauge"
display = "latest"
unit = "jobs"

view can be numeric, chart, or sparkline. Charts and sparklines share the chart pane; sparklines are compact rows for scanning more series at once.

Metric config matches the base metric name. Labelled DogStatsD series are split into distinct series and grouped together in the UI:

requests:1|c|#service:api,host:a
requests:1|c|#service:worker,host:b

Both lines match name = "requests", but render as separate labelled rows/charts.

kind defaults to auto, which uses the kind from received DogStatsD samples. Set it explicitly when adding a metric before samples arrive. display defaults to the current latest-sample view; use rate for counters, or latest/total when you want that value plotted or shown as primary.

Controls

• Tab, Left, Right: switch focus between numeric and chart panes.
• Up/Down or j/k: move the selected metric.
• PageUp/PageDown: page by the visible item count.
• Home/End: jump to first/last item in the focused pane.
• /: filter metrics by name or labels.
• a: add a metric from discovered traffic or a typed base metric name.
• Ctrl-X then Ctrl-S, or Ctrl-X then s: save the current runtime metric config.
• v: cycle the selected metric through numeric, chart, and sparkline views.
• +/-: increase/decrease full chart height.
• Enter: open the selected metric details pane.
• Enter while searching: keep the current filter.
• Esc while searching: stop editing and keep the current filter.
• Ctrl-W while searching: clear the filter input.
• c with an active filter: clear the current filter.
• In the add pane, Up/Down selects a discovered metric, Tab moves between fields, Left/Right changes view/kind/display, Ctrl-V cycles numeric/chart/sparkline, Ctrl-K cycles kind, Ctrl-D cycles display, Ctrl-W clears text fields, Enter adds, and Esc cancels.
• In the details pane, v cycles the metric view and d removes the selected base metric and all of its labelled series from the live dashboard.
• Esc or Enter: close the details pane.
• q, Ctrl-C, or Ctrl-X then Ctrl-C: quit.

Scope

The current focus is fast, low-overhead live visibility for e.g. debugging or quick monitoring.

• No persistence between sessions.
• No querying or joins.
• Fixed-size per-series ring buffers for chart samples.
• Labels/tags are used for series identity and shown in details.

If you want more than this you probably want a real metrics collector, but I'm open to additions where they keep the lightweight focus. Some features I want to add include:

• Adjust series ring buffer size
• Load or switch config from inside the app
• Reset / flush metric

License

spinal-tap is licensed under the GNU General Public License v3.0 only. See LICENSE.