# Grafana recipe

URL: https://briq.cloud/cookbook/grafana

> A dashboard the agent can point at its own data, instead of a STATUS.md it writes by hand.

Tags: app, observability

## Run it

MCP:

```ts
briq_run({
  recipe: "grafana",
  params: {
    "size": "small",
    "diskGb": 1
  },
  wait: true
})
```

REST:

```bash
curl -X POST https://api.briq.cloud/v1/briqs \
  -H "Authorization: Bearer $BRIQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "recipe": "grafana",
    "params": {
      "size": "small",
      "diskGb": 1
    },
    "wait": true
  }'
# → { "briqs": [{ "id": "bq_…", … }], "outputs": { "GRAFANA_URL": "…" }, … }

# ... when done, for each briq id
curl -X DELETE https://api.briq.cloud/v1/briqs/<id> \
  -H "Authorization: Bearer $BRIQ_API_KEY"
```

## Parameters

| Name | Type | Options | Default | What it does |
| --- | --- | --- | --- | --- |
| `size` | enum | nano, small, medium | "small" | — |
| `diskGb` | number | — | 1 | Volume size, in GB |

## Outputs

Returned by `briq_run` once the stack is healthy. Hosts resolve inside your team network; secrets are generated per run.

| Output | Value |
| --- | --- |
| `GRAFANA_URL` | `http://grafana.<stack>.internal:3000` |
| `GRAFANA_ADMIN_USER` | `admin` |
| `GRAFANA_ADMIN_PASSWORD` | `<GRAFANA_ADMIN_PASSWORD>` |

## What it runs

| Briq | Image | Ports | Size | Volume |
| --- | --- | --- | --- | --- |
| grafana | `grafana/grafana:latest` | 3000 | small | 1 GB at /var/lib/grafana |

## When to use it

* The agent reports a load test or a long run as a paragraph of numbers, and you would rather see
  a chart.
* You want dashboards over data the agent's briqs already produce: Postgres, a Prometheus
  endpoint, logs.
* You want to hand someone a live dashboard instead of a note that goes stale.

## Tips

* **Wire it from the API**: `POST /api/datasources` on `GRAFANA_URL` with basic auth
  (`GRAFANA_ADMIN_USER`, `GRAFANA_ADMIN_PASSWORD`).
* **Data sources in the same stack** stay private; only Grafana needs a URL.
* **Dashboards as JSON**: `POST /api/dashboards/db` beats building panels by hand.
* **Share it**: `briq_run({ recipe: "grafana", expose: "private" })`, or `briq_expose` port 3000
  with `mode: "private"`.
* **More room**: the volume starts small; pass `diskGb` for more. Set it when the briq is created,
  and it counts toward your [plan's disk](https://briq.cloud/docs/cost#plans).