# 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.