Skip to main content
Query resource usage for a running sandbox: CPU, memory, and more. Get a single point-in-time snapshot, or open a streaming subscription that delivers updates at a fixed interval. While a sandbox is paused, the runtime skips host page-residency scans and reports memory_host_resident_bytes as unavailable. Host residency can change even when guest execution is stopped, so the runtime does not reuse the previous value. Other metrics continue to be sampled; residency sampling returns on the next sample after resume. OCI sandboxes also expose optional upper filesystem fields for capacity dashboards. Guest-visible upper_used_bytes and upper_free_bytes are available when the protected bundled-kernel reporter is fresh. Host-observed upper_host_allocated_bytes is available when microsandbox can inspect the writable upper image from the host. SDKs surface those as nullable fields because custom kernels and non-OCI roots may not provide them.
Need continuous shipping to Grafana, Datadog, Prometheus, or any other OTel-compatible backend? See msb-metrics, a sidecar binary that reads the same data and ships it over OTLP.

Point-in-time

Streaming

Subscribe to metric updates at a regular interval. Each update arrives as a separate event. Ruby exposes point-in-time metrics only; it does not expose streaming or fleet-wide metrics.

Fleet-wide metrics

Get the latest metrics for every running sandbox at once. Useful for dashboards or capacity planning.
Fleet snapshots only include sandboxes whose runtime process is actually alive. A runtime that crashed without cleanup used to keep reporting its last sample as if the sandbox were running; readers now detect the dead owner and retire the entry on first read. Memory limits follow live memory resizes on current runtimes: per-sandbox metrics, metrics reports, msb metrics, fleet snapshots, and msb-metrics all report the guest’s current memory size. For sandboxes without memory hotplug, or started by an older runtime, per-sandbox metrics and reports fall back to the configured size, while fleet snapshots and msb-metrics report the boot allocation until the sandbox is restarted. Memory usage is the guest memory in use, measured against the live memory size when the runtime reports it. Right after a resize, usage can briefly be off or missing until the guest’s memory statistics catch up. In particular, growing memory can temporarily overstate usage. OTLP omits unavailable usage samples, and the collector’s stdout output displays N/A; SDK numeric usage fields and msb metrics still represent unavailable usage as zero.

Metrics reports

msb metrics joins each sample with catalog information. CPU allocation comes from the active configuration; the memory limit comes from the live sample, falling back to active configuration when unavailable. Reports therefore reflect live resizes. Reports distinguish a fresh sample, a live runtime that has missed three sampling intervals, and the preserved terminal sample of a stopped sandbox. See report states for their definitions. Programmatic reports are currently available only through the Rust report APIs.

Reference

For exact per-sandbox metrics APIs, see TypeScript, Rust, Python, Go, or Ruby. For local reports and fleet snapshots, see msb metrics.

Upgrading with running sandboxes

Upgraded SDK readers search both the registry derived from the normalized home and the legacy registry derived from its original spelling. Existing runtimes keep writing to their current registry and do not need restarting; each newly started run writes only to the normalized-home registry. All metrics APIs validate matches against the catalog and process identity and merge results without duplicate runs. This uses in-memory reader state only: there is no database migration, sidecar, config rewrite, or change to registry cleanup. Keep the original home spelling available when upgrading. Discovering a legacy registry after that spelling is lost is outside this lookup’s scope. Older readers do not automatically gain support for the new registry names.