Skip to main content
msb-metrics is a sibling process. It reads the microsandbox shared-memory metrics registry on a fixed interval and ships per-sandbox metrics to any OpenTelemetry-compatible backend. Think of it the way you’d run otel-collector, prometheus-node-exporter, or fluent-bit: one process per host, lifecycle managed independently. It’s one of three ways to read sandbox metrics. For one-shot inspection from the terminal, use the msb metrics CLI command. For programmatic per-sandbox reads from application code, use Sandbox::metrics(). All three read the same shared-memory registry and can coexist; the diagram below shows how they relate.

​
Where it fits

Three surfaces read the same shared-memory registry. This page is about the highlighted path: a continuous push to an OTel-compatible backend.

​
Install

msb-metrics is shipped as a standalone binary and is not bundled with the main msb installer. Download the build for your platform from the latest release and place it on your PATH.

​
Quick start

1

Run msb-metrics against a local OTLP receiver

Default port 4317. Recommended for most local OTLP collectors and sidecars.
msb-metrics otel --endpoint=http://localhost:4317
2

Boot a sandbox

msb run alpine
3

Watch metrics flow

The collector polls shared memory every second, batches per-exporter, and ships over OTLP. Press Ctrl+C to drain buffers and exit cleanly.

​
Pick your backend

End-to-end setup walkthroughs live under Recipes:

Grafana Cloud

Direct OTLP to Grafana Cloud’s gateway.

Grafana Alloy

Local Alloy as a forwarder. Recommended for production.

Prometheus

Direct OTLP to Prometheus’s native receiver.

otel-collector

Local development with the OpenTelemetry Collector.

Datadog

Via the Datadog Agent’s OTLP receiver.

​
Labels and per-user views

Labels you set at sandbox creation ride along to your backend as metric attributes, so you can build per-user, per-tenant, or per-environment views without naming every sandbox. 
msb create alpine --name worker-1 --label user.id=alice --label tenant=acme
msb-metrics reads those labels from the catalog and attaches them to every datapoint emitted for that sandbox.

​
Label names in PromQL

OpenTelemetry attribute keys allow dots; Prometheus label names do not, so Prometheus and Grafana Cloud normalize . to _. A label set as user.id is queried as user_id. (Metric names are normalized the same way: microsandbox.cpu.utilization becomes microsandbox_cpu_utilization.)

​
Per-user dashboard queries

Use the labels to slice the standard sandbox metrics. CPU is the simplest to start with (the same labels apply to every metric — see the metric table): 
# CPU per user (vCPU-seconds per second)
sum by (user_id) (microsandbox_cpu_utilization)

# Top 10 users by CPU right now
topk(10, sum by (user_id) (microsandbox_cpu_utilization))

# One user's sandboxes
microsandbox_cpu_utilization{user_id="alice"}

# Scope to a tenant as well
sum by (user_id) (microsandbox_cpu_utilization{tenant="acme"})
To make a reusable dashboard, add a Grafana template variable so the panels follow a dropdown: 
Variable:  user
Query:     label_values(microsandbox_cpu_utilization, user_id)
Panels:    microsandbox_cpu_utilization{user_id="$user"}
Labels are on by default. Pass --no-labels to turn them off, e.g. when a high-cardinality key like user.id would inflate active-series billing. To drop individual noisy keys while keeping the rest, repeat --exclude-label-key <key> (e.g. --exclude-label-key org.opencontainers.image.revision); the key stays in the catalog for msb inspect and is only withheld from metrics. See the Deep dive for the cardinality trade-offs.

​
Reference

For flags, metric names, attribute tables, operational notes, and troubleshooting, see the Deep dive.

​
See also

  • Deep dive: flags, emitted metrics, attributes, operations, troubleshooting.
  • Sandbox::metrics(): read metrics for a single sandbox from application code, an alternative to shipping via OTLP.
  • msb metrics: one-shot CLI inspection of current per-sandbox metrics.