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
- gRPC (default)
- HTTP/Protobuf
Default port
4317. Recommended for most local OTLP collectors
and sidecars.2
Boot a sandbox
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 on a sandbox 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-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):--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.