Spider-mon CLI - self-monitoring as a structured query, not a dashboard scroll
Spider has a full self-monitoring GUI: parsing pipeline metrics, agent states, Redis and Elasticsearch internals, service CPU and latency, log search. It is great for browsing and for opening on a screen during an incident.
It is less great when the question is "diff the last hour against last week, on this specific metric".
Or "give me a new performance metrics".
Or "did the upgrade I just rolled out actually move any metric?".
These are queries, not dashboards.
spider-mon is the CLI for those questions.
What it is
spider-mon is a sibling of spider CLI. Same Go codebase shape, same ~/.spider/profiles.json configuration, same .xz-packaged static binaries for Linux / macOS / Windows on amd64 and arm64. If you already have a Spider profile configured for spider, spider-mon reuses it - no extra setup.
Where spider returns captured traffic (HTTP, PSQL, TCP, packets), spider-mon returns Spider's own health - the same data the Self-Monitoring GUI shows, exposed as JSON so it can be diffed, baselined, piped into jq, or fed to an AI agent.
What it covers
The CLI is organised around pages. Each page mirrors a tab of the Self-Monitoring GUI and returns a JSON envelope with one entry per graph:
| Page | What it shows |
|---|---|
health | Probe statuses |
parsing | TCP / HTTP / PSQL parsing pipeline metrics |
services | Service CPU, RAM, API latency, polling queues |
whisperers | Whisperer agent states, CPU / RAM, queue overflow, latency |
gociphers | Gocipher agent states, CPU / RAM, queue overflow, latency |
redis | Redis instance internals: keys, memory, commands/sec, circuit breakers |
elasticsearch | Elasticsearch per-index content, size, load, circuit breakers |
infra | Host nodes and Kubernetes workloads from the cluster side |
cb | Circuit-breaker errors across agents, services, datastores |
logs | Error / warning log counts by service and by service / code |
status | All pages in parallel - one-shot rollup of the whole stack |
By default, every page returns a {avg, max, last} summary per graph. Pass --full to include the full time-series array. Pass a graph name as a positional argument to keep only that graph.
There is also a search verb for raw log items - spider-mon search logs (Filebeat-shipped service logs) and spider-mon search guilogs (Network-View / Login / Self-Monitoring browser logs). Both accept Lucene queries, level filters, and time ranges, and return raw logs JSON items.
The killer feature: baselines
A few months back this would have been a nice-to-have. After this release, with the Node-to-Go pipeline migration landing in the same release, it became the thing that turned the rewrite from "we think it's faster" into "here is the proof".
Two commands:
spider-mon status --save pre-upgrade- take a snapshot of every page on the current cluster and store it locally at~/.spider/baselines/pre-upgrade.json.spider-mon status --compare pre-upgrade- take a fresh snapshot and diff it against the stored baseline, threshold-filtered.
That is the workflow that produced the performance comparison in the Go migration blog post. Snapshot the old stack. Snapshot the new stack. Diff. The same comparison can be sliced to a single page (spider-mon parsing --compare pre-upgrade) when you only care about one part of the system.
Baselines have a few practical properties worth pointing out:
- They are local files. Versionable, attachable, shareable, scriptable.
--savealways writes a full-page baseline;--compareslices it to match the live shape, so you can save in full and compare in summary.- The
baselinesubcommand (spider-mon baseline list / delete) manages them.
The same pattern works for any "did this change matter?" question: before vs after a configuration change, week-over-week to spot drift, before vs after onboarding a new heavy customer.
Where it adds value
A few of the patterns we've found ourselves using:
Snapshots as evidence.
spider-mon status --pretty > status-$(date +%FT%H%M).json produces a self-contained, machine-readable snapshot of the cluster that can be attached to a postmortem, an upgrade report, or a Slack thread. The JSON encodes both summary numbers and (if --full is passed) the underlying time-series, so an analyst opening it later can read the shape, not just the average.
Tight log search.
spider-mon search logs --service Pg --level error --start -24h | jq is faster than navigating to the GUI logs tab, picking the service filter, picking the level filter, and scrolling. The --service is a prefix match, so Pg covers Pg-Parser, Pg-Read, Pg-Upload; combine with --query for additional Lucene clauses.
Period-over-period diffs.
Save Monday-morning. Compare Tuesday-morning. Anything that moved by more than the threshold shows up; everything that didn't is silent.
The Self-Monitoring GUI shows you the current shape; the CLI tells you what changed.
What this looks like for an AI agent
The Spider-mon Claude Code plugin (in the spider-analyzer marketplace) wraps spider-mon with skills and agents purpose-built for monitoring review - reactive troubleshooting on one side, proactive tuning advice on the other.
The flow we use most often:
- a Spider alert email arrives,
- paste it into Claude Code with the plugin installed,
- get back a structured diagnosis (which service, which graph, when did it start, what is the likely root cause, what command to run next) within a couple of minutes. No dashboard scroll required.
The full skill / agent inventory and how it composes with the Spider traffic plugin are covered in Spider's Claude Code plugins.
Installation
spider-mon binaries are published next to the Spider CLI ones, at https://repository.floocus.com/bin/spider-mon-<os>-<arch>/<version>/spider-mon.xz. Same static-binary, no-runtime-dependency build as spider.
If you already have a Spider profile from the Spider CLI, no extra setup is needed - spider-mon reads from the same ~/.spider/profiles.json. Override per-command with --profile <name>.
Full reference: /docs/tools/spider-mon (CLI) and /docs/tools/spider-mon-plugin (Claude Code plugin).
Closing
A dashboard is a beautiful thing for a human staring at one. It is a terrible thing for a human comparing two, a script asserting on three, or an AI agent reasoning about a dozen.
spider-mon does not replace the Self-Monitoring GUI - it complements it with a structured surface that the GUI cannot provide.
The baselines feature in particular has changed how I think about performance work on Spider itself. The Go migration was the first project where every step was measurable. I expect every future one to be the same.