swarm-metrics
An agent's CLI for the swarm metrics store (VictoriaMetrics), the sibling of
swarm-logs. Each verb is one read against the store's Prometheus-compatible
API through the gateway, and prints the store's JSON answer unchanged, for
jq.
| verb | store endpoint | for |
|---|---|---|
query |
/api/v1/query |
a MetricsQL expression at one instant |
query-range |
/api/v1/query_range |
the same over a window; needs --start |
series |
/api/v1/series |
which series match a selector |
labels |
/api/v1/labels |
label names |
label-values |
/api/v1/label/<name>/values |
one label's values (__name__: names) |
Read-only: nothing here writes, and the gateway serves no write path to this caller.
⚠️ No scoping
The gateway forwards the request unmodified, so any authenticated caller reads the whole swarm's metrics, every hive's.
How it authenticates
As the agent itself, exactly as swarm-logs does: on each request it reads
the agent's own queue secret, swarm/agents/<agent>/queue, from the swarm
secret store with the agent's store certificate, and sends
Authorization: Bearer swarm-agent.<agent>.<secret>. A 401 makes it read the
secret again and retry once.
On the metrics store's host, nginx hands a bearer of that shape to
swarm-metrics-agent-auth, a swarm-logs-auth instance logged in to the
store under that host's swarm-metrics-auth leaf. It grants a secret it has
verified for 60 s by default (deploy.victoriametrics.agentAuthVerdictTtl).
A 403 is the gateway's per-address rate limit on these checks, and
swarm-metrics doesn't retry it.
🩸 The secret is never logged or rendered into an error.
Configuration
Supplied by nix/agent-modules/metrics.nix, which wraps the binary.
| variable | what |
|---|---|
HIVE_AGENT_METRICS_URL |
the metrics store's gateway origin |
HIVE_AGENT_NAME |
this agent's name; the store path and role |
BAO_ADDR |
the secret store's address |
BAO_CLIENT_CERT |
path of the agent's live store certificate |
BAO_CLIENT_KEY |
path of its key |
BAO_CACERT |
path of the store's CA; missing or empty is fine |
With no HIVE_AGENT_METRICS_URL the binary says there is no metrics store;
with the URL and no store address it reports a deployment bug by name.
Output
The store's response body, unmodified, newline-terminated. A non-2xx exits non-zero with its status and body on stderr, never as an empty result.