# 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_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](https://html.spec.whatwg.org/multipage/server-sent-events.html):

- `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](https://sandbox.wbx.cz/docs/sdk/typescript.md): `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](https://sandbox.wbx.cz/docs/jobs/batches.md#usage).

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

Source: https://sandbox.wbx.cz/docs/sandboxes/metrics
