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.
- 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. The panel’s title starts as Run
--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:terminal
Output
Explore; edit it in the file:deploy/observability/dashboards/reports.json
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
terminal
Output (trimmed)
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
terminal
Output (trimmed)
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
groupBy[0]: field "procedure" is not valid on metrics
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.single_bucket: the answer holds one bucket
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
Add a custom metric
Record a business metric to put on your dashboard.
Alert rules as code
Turn a panel’s query into an alert that ships the same way.
Hosted dashboards and alerts
Generated, repo and workspace dashboards, and every panel kind.
Querying with forge obs
Every obs verb and flag.