Metrics collector

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

mermaid

flowchart TD
    classDef store fill:#f5f5f5,stroke:#9d9d9d,color:#333
    classDef thispage fill:#bf84fe,color:#fff,stroke:#9d5fe0

    SB1[Sandbox A]
    SB2[Sandbox B]
    SB3[Sandbox N]
    SB1 -->|writes samples| SHM
    SB2 -->|writes samples| SHM
    SB3 -->|writes samples| SHM
    SHM[("Shared-memory
registry")]:::store

    SHM -->|read| CLI["msb metrics
(CLI, one-shot)"]
    SHM -->|read| SDK["Sandbox::metrics
(SDK, in-process)"]
    SHM -->|read| MSB["msb-metrics
(sidecar, continuous)"]:::thispage

    CLI --> TERM[Terminal output]
    SDK --> APP[Your application]
    MSB -->|OTLP gRPC/HTTP| BACKEND["Backend
(Grafana / Datadog / …)"]:::thispage

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

<Steps> <Step title="Run msb-metrics against a local OTLP receiver"> <Tabs> <Tab title="gRPC (default)"> Default port `4317`. Recommended for most local OTLP collectors and sidecars.

    ```sh
    msb-metrics otel --endpoint=http://localhost:4317
    ```
  </Tab>
  <Tab title="HTTP/Protobuf">
    Default port `4318`. Use when the backend's gRPC port isn't
    reachable, or when the gateway expects HTTP (e.g. Grafana
    Cloud's OTLP gateway over HTTPS).

    ```sh
    msb-metrics otel --endpoint=https://example.com/otlp/v1/metrics --protocol=http
    ```
  </Tab>
</Tabs>

</Step> <Step title="Boot a sandbox"> ```sh msb run alpine ``` </Step> <Step title="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. </Step> </Steps>

Pick your backend

End-to-end setup walkthroughs live under Recipes:

<CardGroup cols={2}> <Card title="Grafana Cloud" icon="cloud-arrow-up" href="/recipes/metrics-backends/grafana-cloud"> Direct OTLP to Grafana Cloud's gateway. </Card> <Card title="Grafana Alloy" icon="route" href="/recipes/metrics-backends/grafana-alloy"> Local Alloy as a forwarder. Recommended for production. </Card> <Card title="Prometheus" icon="fire" href="/recipes/metrics-backends/prometheus"> Direct OTLP to Prometheus's native receiver. </Card> <Card title="otel-collector" icon="terminal" href="/recipes/metrics-backends/otel-collector"> Local development with the OpenTelemetry Collector. </Card> <Card title="Datadog" icon="chart-line" href="/recipes/metrics-backends/datadog"> Via the Datadog Agent's OTLP receiver. </Card> </CardGroup>

Reference

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

Where it fits

Install

Quick start

Pick your backend

Reference

See also