One agent, one endpoint, one configuration file. This page is the whole reference.
/etc/sc-agent.conf — keys are flat, values are unquoted.
| Key | Default | Notes |
|---|---|---|
endpoint | — | Required. Full URL including /api/v1/data. |
key | — | Required. Sent as X-Agent-Key. Read once at start. |
window | 30s | Sampling interval. Minimum 10s, maximum 300s. |
collect | cpu, mem, disk | Comma separated. Also net, systemd, procs. |
host | hostname | Override when the hostname is not stable across reboots. |
proxy | env | Falls back to HTTPS_PROXY when unset. |
queue | 20 | Windows held in memory before the oldest is discarded. |
The agent re-reads the file on SIGHUP. Changing window takes effect at the next window boundary, not immediately, so buckets stay aligned across the fleet.
POST /api/v1/data — the only endpoint an agent ever calls.
POST /api/v1/data HTTP/1.1
Host: slatecadence.com
Content-Type: application/json
Content-Encoding: gzip
X-Agent-Key: sk_live_xxxxxxxxxxxxxxxx
{"host":"web-03","window":30,"ts":1789102800,
"series":[{"k":"cpu.busy","v":0.41},{"k":"mem.used","v":6291456}]}Bodies may be gzipped; the agent does so above 4 KB. Maximum accepted body is 1 MB decompressed. Batches above that are rejected rather than truncated — lower queue or raise window.
| Status | Meaning | Agent behaviour |
|---|---|---|
204 | Batch accepted. | Window dropped from the queue. |
207 | Accepted, some series rejected. Count in X-Rejected. | Window dropped; warning logged. |
400 | Body is not valid JSON or fails schema. | Window discarded, never retried. |
401 | Missing or unknown agent key. | Retry with backoff to 5 min. |
413 | Body over the size limit. | Window discarded, warning logged. |
429 | Per-key rate limit. Retry-After is set. | Sleeps for Retry-After, keeps the queue. |
5xx | Server side. | Retry with backoff; queue drains oldest first. |
Fixed vocabulary per collector. Unknown keys are rejected, not stored.
| Collector | Keys |
|---|---|
cpu | cpu.busy, cpu.iowait, cpu.steal, cpu.load1 |
mem | mem.used, mem.cached, mem.swap, mem.pressure |
disk | disk.used, disk.io.r, disk.io.w, disk.await |
net | net.rx, net.tx, net.drop, net.retrans |
systemd | svc.failed, svc.restarts, svc.p95 |
procs | proc.count, proc.zombie, proc.fds |
In rough order of how often it turns out to be the cause.
Egress proxy swallowing the POST. Run sc-agent --probe: it performs one synchronous request and prints the full exchange.
Usually a host suspending. The agent does not backfill across a suspend — the queue is in memory by design.
A collector emitting a key outside the vocabulary above, normally after a partial upgrade. Check sc-agent --version across the fleet.
Windows whose ts is more than 10 minutes from server time are rejected with 400. Fix NTP before anything else.