ContextQMD
Back to Microsandbox

Grafana Cloud

docs/examples/metrics-backends/grafana-cloud.mdx

0.6.103.2 KB
Original Source

<Tooltip tip="This page covers msb-metrics, which reads host-local shared memory and is local-only. It does not apply to microsandbox cloud sandboxes."><span className="msb-badge-local">Local-only <Icon icon="circle-info" size={11} /></span></Tooltip>

<Note> This example ships data emitted by [`msb-metrics`](/observability/msb-metrics). See the msb-metrics page for the flag reference, metric names, and deployment constraints. </Note>

Grafana Cloud exposes a region-specific OTLP gateway at otlp-gateway-prod-<region>.grafana.net. msb-metrics ships directly to it using HTTP/Protobuf and Basic auth.

Connect Grafana Cloud

<Steps> <Step title="Get your OTLP endpoint and credentials"> In the Grafana Cloud admin console, open **My Account → Connections → OpenTelemetry**. Copy three values: 
- **Endpoint URL** (looks like
  `https://otlp-gateway-prod-us-east-2.grafana.net/otlp`)
- **Instance ID** (a numeric instance identifier)
- **API token** with scope `metrics:write` (create one if you
  don't already have it)
</Step> <Step title="Build the Basic auth header"> Grafana Cloud's OTLP gateway uses HTTP Basic auth, where the username is your instance ID and the password is the API token. 
<CodeGroup>
```sh macOS & Linux
GC_ID=...      # numeric instance id
GC_TOKEN=...   # API token with metrics:write
AUTH="Basic $(printf '%s:%s' "$GC_ID" "$GC_TOKEN" | base64 | tr -d '\n')"
```

```powershell Windows
$env:GC_ID = '...'      # numeric instance id
$env:GC_TOKEN = '...'   # API token with metrics:write
$credentials = "$env:GC_ID`:$env:GC_TOKEN"
$auth = 'Basic ' + [Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes($credentials))
```
</CodeGroup>
</Step> <Step title="Run msb-metrics"> <CodeGroup> ```sh macOS & Linux msb-metrics otel \ --endpoint=https://otlp-gateway-prod-us-east-2.grafana.net/otlp/v1/metrics \ --protocol=http \ --header="Authorization=${AUTH}" ``` 
```powershell Windows
msb-metrics otel `
  --endpoint=https://otlp-gateway-prod-us-east-2.grafana.net/otlp/v1/metrics `
  --protocol=http `
  --header="Authorization=$auth"
```
</CodeGroup>

Substitute your region in the URL. If Grafana shows you the base
OTLP URL ending in `/otlp`, append `/v1/metrics` for this HTTP
metrics-only exporter.
</Step> <Step title="Verify"> Boot a sandbox (`msb run alpine`) and open Grafana → **Explore**. Query `microsandbox_cpu_utilization` (PromQL view of the OTel `microsandbox.cpu.utilization` gauge). You should see data within the next flush interval (default 10s). </Step> </Steps>

Production: prefer Grafana Alloy

For long-running deployments, point msb-metrics at a local Grafana Alloy instance instead of the OTLP gateway directly. Alloy handles batching, retries, credential rotation, and buffering through Grafana Cloud hiccups without touching msb-metrics.

Reference