Metrics and observability
How busy is your sandbox? CPU, memory, network and disk of every running sandbox, measured every 10 seconds, with one hour of history, a live stream and charts in the portal.
What is measured
The values come from the server that runs the sandbox ("source": "host"), not from the system inside it – so they also work when the sandbox is busy, and your code cannot change them.
| Field | Meaning |
|---|---|
| t | Time of the sample, Unix milliseconds. |
| cpu_pct | CPU used in the last interval as a percentage of all vCPUs of the sandbox together (0–100; 50 on a 2-vCPU sandbox = one core fully busy). |
| cpu_ms | CPU time used since the sandbox started or woke up, in milliseconds. |
| mem_mb | Memory the sandbox's virtual machine holds on the server, in MB. It includes the file cache of the sandbox's disk and a small overhead of the virtual machine, so it can be higher than free inside the sandbox and close to the sandbox size even when your program is small. |
| net_rx_bytes, net_tx_bytes | Bytes into the sandbox (downloaded) and out of it (uploaded) since it started or woke up – all traffic, IPv4 and IPv6. |
| net_rx_packets, net_tx_packets | Packets in and out since it started or woke up. |
| net_rx_bps, net_tx_bps | Network speed in the last interval, in bytes per second. |
| disk_read_bytes, disk_write_bytes | Bytes read from and written to the sandbox's disk since it started or woke up. |
| disk_read_bps, disk_write_bps | Disk speed in the last interval, in bytes per second. |
- Accuracy. Speeds and
cpu_pctare averages over the interval (about 10 seconds) – a short burst shows up smaller than it was. A value that cannot be measured on a server is reported as 0. Writes may reach the disk a little later than your program made them (file cache). - Inside the sandbox.
GET /v1/sandboxes/{id}/metricsstill returns the current values reported by the system inside the sandbox (CPU count and usage, memory and disk space). It needs a running sandbox and wakes up a sleeping one.
History
The last hour (up to 360 samples, one every 10 seconds) is kept for each running sandbox. When the sandbox ends or falls asleep, its history is discarded; after it wakes up, the history and the counters start again. History is kept in memory only – after maintenance of the server it may start again too.
curl -s "https://sandbox.wbx.cz/v1/sandboxes/SB_ID/metrics/history?since=0" -H "Authorization: Bearer YOUR_API_KEY"
{"source": "host", "interval_s": 10, "retention_s": 3600, "vcpu": 2, "mem_mb": 2048, "state": "running",
"samples": [{"t": 1795176000000, "cpu_pct": 37.5, "cpu_ms": 51230, "mem_mb": 812,
"net_rx_bytes": 104857600, "net_tx_bytes": 2097152, "net_rx_packets": 75012, "net_tx_packets": 31377,
"net_rx_bps": 1048576, "net_tx_bps": 20480,
"disk_read_bytes": 52428800, "disk_write_bytes": 10485760, "disk_read_bps": 0, "disk_write_bps": 409600}]}
Poll with since set to the t of the newest sample you have, to get only new samples.
from wbxsandbox import Sandbox
sb = Sandbox.connect("SB_ID")
h = sb.metrics_history()
for s in h["samples"][-6:]: # the last minute
print(s["t"], s["cpu_pct"], s["mem_mb"], s["net_rx_bps"])
Live stream
GET /v1/sandboxes/{id}/metrics/stream sends Server-Sent Events:
event: statefirst – the sandbox state, e.g.{"state": "running", "interval_s": 10},event: samplewith every new sample (the same fields as in the history),- a comment line
: pingevery 15 seconds when there is nothing to send, event: endlast, with{"reason": "timeout"}after 15 minutes (connect again to continue),"not_running"when the sandbox falls asleep (preceded by astateevent) or"ended"when it is destroyed.
Without since you get only new samples; with ?since=<unix ms> the samples you missed come first, and ?since=0 sends the whole stored history (up to an hour) before the live samples.
curl -N "https://sandbox.wbx.cz/v1/sandboxes/SB_ID/metrics/stream" -H "Authorization: Bearer YOUR_API_KEY"
for ev in sb.metrics_stream():
if ev["event"] == "sample":
print(ev["data"]["cpu_pct"], ev["data"]["mem_mb"])
elif ev["event"] == "end":
print("stream ended:", ev["data"]["reason"])
In the TypeScript SDK: sandbox.metrics.history({ since }) and sandbox.metrics.stream({ reconnect: true }), which can reconnect after the 15 minutes and continue without repeating samples.
Jobs and batches
Background jobs measure their own usage inside the VM: usage of a job has cpu_ms and peak_memory_mb (null when they could not be measured). The summary of a batch adds it up in usage – total CPU time, the highest peak memory, total run time, attempts and retries – and its JSON report has cpu_ms and peak_memory_mb for each job. See Batches.
Sleeping and archived sandboxes
Metrics never wake a sleeping sandbox and do not count as activity – an open chart does not keep a sandbox awake. For a sleeping sandbox the history returns its state and no samples ("state": "sleeping" or "archived", "samples": []), and the stream sends its state and ends right away.
In the portal
Open Sandboxes and click Metrics on a sandbox: charts of CPU, memory, network and disk over the last hour, refreshed every 15 seconds, with a table of the values (one row per minute) for screen readers and copying.
Limits
- History: up to 30 requests per minute per sandbox – polling every 10 seconds is plenty.
- Stream: up to 10 new connections per minute per sandbox and 10 open streams per account; each stream ends after 15 minutes.
- Over the limit the API answers
429with"code": "rate_limited"and aRetry-Afterheader. - Metrics history is an optional feature. When it is not enabled for your account, both endpoints answer
403with"code": "feature_disabled";GET /v1/features(features()in the Python SDK,wbx.features()in the TypeScript SDK) tells you what is enabled.