WBX Sandbox
Sandboxes

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.

FieldMeaning
tTime of the sample, Unix milliseconds.
cpu_pctCPU 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_msCPU time used since the sandbox started or woke up, in milliseconds.
mem_mbMemory 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_bytesBytes 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_packetsPackets in and out since it started or woke up.
net_rx_bps, net_tx_bpsNetwork speed in the last interval, in bytes per second.
disk_read_bytes, disk_write_bytesBytes read from and written to the sandbox's disk since it started or woke up.
disk_read_bps, disk_write_bpsDisk speed in the last interval, in bytes per second.
  • Accuracy. Speeds and cpu_pct are 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}/metrics still 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: state first – the sandbox state, e.g. {"state": "running", "interval_s": 10},
  • event: sample with every new sample (the same fields as in the history),
  • a comment line : ping every 15 seconds when there is nothing to send,
  • event: end last, with {"reason": "timeout"} after 15 minutes (connect again to continue), "not_running" when the sandbox falls asleep (preceded by a state event) 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 429 with "code": "rate_limited" and a Retry-After header.
  • Metrics history is an optional feature. When it is not enabled for your account, both endpoints answer 403 with "code": "feature_disabled"; GET /v1/features (features() in the Python SDK, wbx.features() in the TypeScript SDK) tells you what is enabled.