> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reliantlabs.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Build a dashboard in the UI and keep it as code

> Build a dashboard panel by panel in the console or from the terminal, commit it as a file that ships with every release, and check that each panel has data.

By the end of this guide you will have a dashboard file in `deploy/observability/dashboards/`, checked by forge, shipped inside your next release and audited in production. You can build it by clicking in the console and promoting it, or from the terminal, which is also how an agent builds one. Both produce the same file, because the console stores dashboards in forge's dashboard format.

A dashboard in the repo is reviewed in pull requests and travels with the release that needs it, so promoting a release brings its dashboards and an older release brings back the older set.

## Before you begin

* A Forge project deployed to Reliant hosting: [Deploy a Go API with managed Postgres](https://docs.reliantlabs.io/guides/hosting/deploy-go-api-managed-postgres.md).
* To build in the console: the admin role in your organization. Members can view dashboards; only admins can create, edit or promote them.
* Forge v1.6.1 or later in the project (`reliant forge --version`).

**1. Build the dashboard in the console**

Open **Dashboards** for your project in the console and choose **New dashboard**: blank, from a template, or by importing a forge dashboard file. **Add panel** opens a builder where you pick a visualization, a signal (metrics, traces or logs), series with an aggregation, filters, a group-by and units, with a live preview. The **Spec** tab shows the panel's JSON. Each **Save** is a new version, with history and restore.

This is a **workspace** dashboard: it lives in the console, not in your repo.

**2. Promote it to code**

On the dashboard, choose **Promote to code**. The dialog shows the file and where it goes, `deploy/observability/dashboards/<slug>.json`. Choose **Download** (or **Copy**) and save it at that path in your repo.

If the dialog warns that the name replaces a generated dashboard, the file will take that dashboard's place in releases. Rename the file and its `id` to keep both.

**3. Or build it from the terminal**

Without the console, start from a metrics query. `--panel-out` writes the panel the query would draw instead of running it, and `add-panel` appends it to a dashboard file, creating the file if needed:

```bash terminal theme={null}
reliant forge obs metrics query prod rpc.server.calls --agg rate \
  --group-by metric.attr.procedure --panel-out calls.json
reliant forge obs dashboards add-panel reports --panel calls.json \
  --id calls-by-rpc --title "Reports"
```

```text Output theme={null}
added panel "calls-by-rpc" (1 panel(s))
deploy/observability/dashboards/reports.json
suggested: forge obs dashboards check
```

The panel's title starts as `Explore`; edit it in the file:

```json deploy/observability/dashboards/reports.json theme={null}
{
  "version": "forge.dashboards/v1",
  "id": "reports",
  "title": "Reports",
  "panels": [
    {
      "id": "calls-by-rpc",
      "title": "Calls per second by RPC",
      "kind": "line",
      "signal": "metrics",
      "series": [
        { "label": "A", "agg": "rate", "field": "rpc.server.calls", "metricType": "sum" }
      ],
      "groupBy": ["metric.attr.procedure"]
    }
  ]
}
```

Run `add-panel` again to add more panels; `--replace` swaps a panel with the same id. An invalid panel writes nothing and names the line and column at fault.

**4. Check the dashboards the next release will carry**

```bash terminal theme={null}
reliant forge obs dashboards check
```

```text Output (trimmed) theme={null}
  gen  observability/dashboards/guides-sandbox-users-workloads_gen.json  (14 panel(s))
  user observability/dashboards/reports.json  (1 panel(s))
       observability/metrics-schema.json
13 dashboard(s) would ship
```

`check` validates every file exactly as a release cut does, so a broken dashboard fails here rather than in your build. `user` marks your file; `gen` marks the ones forge generates. To also check each metrics panel against real telemetry, add `--against prod`: a metric stored as a different kind than the panel expects fails, and a metric with no data is reported (`--strict` fails on that too).

**5. Ship it**

Commit the file and deploy a release the usual way, for example `reliant forge env deploy prod v1.5.0 --yes`. In the console, the dashboard now shows as a **Repo** dashboard: read-only, because the file is its source. To change it, edit the file, or use **Save as copy** to fork it into a new workspace dashboard and promote that.

**6. Check that every panel has data**

```bash terminal theme={null}
reliant forge obs dashboards audit prod --dashboard reports --all
```

```text Output (trimmed) theme={null}
1 dashboard(s), 1 panel(s): 0 error, 0 empty, 0 partial, 1 ok, 0 n/a

STATUS  PANEL                 KIND  DATA                        STEP  REASON
ok      reports/calls-by-rpc  line  1 series, 1/3 pts non-zero  1m
```

`audit` runs each panel the way the console does. An `empty` panel is probed over a wider window and every environment, and the reason says whether the data exists elsewhere or nowhere. The command exits 0 when every panel is `ok`, 2 when one is empty or partial, and 1 when one could not be read, so a script or an agent can act on it.

## What this does not do

* **Promote to code does not open a pull request.** It gives you the file; you commit it.
* **A repo dashboard is not edited in the console.** The file is the source, so a change made by clicking would be lost on the next release. Fork it with **Save as copy** instead.

## Troubleshooting

> [accordion] groupBy\[0]: field "procedure" is not valid on metrics
>
> A dashboard file names a metric attribute as `metric.attr.<key>`. Run the query with `--group-by metric.attr.procedure` before `--panel-out`, or fix the key in the panel file.

> [accordion] single\_bucket: the answer holds one bucket
>
> `audit` reports a line panel as `partial` when the window holds only one data point. Metrics export every 60 seconds; wait a few minutes after the first traffic, or pass a longer `--since`.

## Next steps

> [card] [Add a custom metric](https://docs.reliantlabs.io/guides/observability/add-custom-metric.md)
>
> Record a business metric to put on your dashboard.

> [card] [Alert rules as code](https://docs.reliantlabs.io/guides/observability/custom-alert-rules-as-code.md)
>
> Turn a panel's query into an alert that ships the same way.

> [card] [Hosted dashboards and alerts](https://docs.reliantlabs.io/hosting/observability/dashboards-and-alerts.md)
>
> Generated, repo and workspace dashboards, and every panel kind.

> [card] [Querying with forge obs](https://docs.reliantlabs.io/hosting/observability/forge-obs.md)
>
> Every obs verb and flag.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.