Skip to content
Back to skills

Dashboards

ASecurity

Process/role dashboards derived from deployed executable and composition commands, metric-backed overview, the built-in Product overview, Users, Product and Acquisition dashboards and the Overview's Traffic and Users sections (pkg/obsbuiltin), renderer-neutral sections and targeted filters, safe retirement and overrides, and HyperDX delivery.

  • 10 stars
  • 0 votes
  • 0 copies
  • 1 view
  • Added November 13, 2026
developmentgosqlnodeexpresskubernetesawsapidatabasefrontendbackend

Works with

  • cli
  • api

Security analysis

A100/100

Pro scans all 2 files and shows the line behind each finding

Scanned November 18, 2026

npx -y skills add reliant-labs/forge --skill dashboards --agent claude-code

Installs into .claude/skills of the current project.

Are you the author of Dashboards?

Add the live security badge to your README. It updates with every re-scan.

Security grade badge for Dashboards
[![Security: A — Skills Directory](https://www.skillsdirectory.com/api/skills/reliant-labs-dashboards-7ef1d1fa/badge)](https://www.skillsdirectory.com/skills/reliant-labs-dashboards-7ef1d1fa)

More formats (shields.io, HTML) on the badges page. Keep it an A: scan every change in CI with Pro.

Download with Pro
SKILL.md
---
name: observability/dashboards
description: Process/role dashboards derived from deployed executable and composition commands, metric-backed overview, the built-in Product overview, Users, Product and Acquisition dashboards and the Overview's Traffic and Users sections (pkg/obsbuiltin), renderer-neutral sections and targeted filters, safe retirement and overrides, and HyperDX delivery.
---

# Observability: generated dashboards

Every dashboard declares a `group` (overview, services, jobs, product, ai, platform, releases or custom; a reader that predates `ai` lists it under custom) and optional `tags`, which only a list view reads; `replaces` lists the ids a renamed generated dashboard supersedes, so a reader can carry stars and copies over. A process dashboard is named for the forge workload (`admin-api`), never the rendered Job/command/hash. An env that deploys no process (a static site) gets only its frontend dashboard, and the frontend dashboard follows the frontends that env serves.

`forge generate` writes reusable RPC, frontend and metric dashboard fragments
and alert inputs without claiming process ownership. It scopes the overview to
the service.names and workloads every environment that renders declares (the
same derivation a bundle uses), so the local stack's overview draws your
processes; an environment that does not render is skipped, so a newly scaffolded
operator can still generate while prod's cluster is unbound. The local overview
(`<project>-overview.json`) is yours once written, but while it is still the
untouched render of "nothing deployed" (every panel on
`__forge_no_deployed_process__`) the next generate that finds workloads
replaces it; an edited one is never touched.

`forge env render <env>` validates, and `forge env build <env>` assembles the
process dashboards from the selected environment's already-rendered
`KCLEntities.Workloads`. The exact executable, command/args and resolved
`OTEL_SERVICE_NAME` include environment-only workloads and aliases. No source
`ALL` inventory, AST workload guesses, second render or other-environment validity
is involved. API, worker and gateway roles of one executable remain separate;
workers with no RPCs get runtime/workload panels. Composition route sets and typed
mounts establish RPC ownership, not proto package names.

Per-process assembly is pure and environment-specific. It writes no global process
parts and retires nothing on a failed render. Each release bundle contains exactly
its selected environment's dashboard set, with owned process overrides applied by
stable ID/filename. Old disk-generated process parts never contaminate that set.

| File                                                          | What                                                                                                                                                                                             |
| ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `deploy/observability/dashboards/<project>-overview_gen.json` | Compact unsampled request/error counters and duration histogram health; process comparison, saturation, errors and releases |
| `.../<project>-process-<workload>_gen.json` | One long-running service, worker or operator, named for its forge workload. Panels follow what it does: RPC health only if it serves RPCs, worker runs for workers and operators, database when reached, a `*_limit_utilization` panel only for a declared limit, runtime and logs always |
| `.../<project>-frontend_gen.json`                             | with a web frontend: JS errors, sessions, page views, failed API calls, LCP/INP/CLS p75, page-load percentiles, browser API latency and calls by URL — scoped to the web frontends' `service.name`s (`<project>-<frontend>`, otel_gen.ts's `SERVICE_NAME`; a frontend built from another repository (`source`) bakes that repository's name, so declare it: `telemetry = forge.BrowserTelemetry {service_name = "shop-web"}`) |
| `.../<project>-process-<workload>_gen.ndjson` | Process error-log saved search |
| `.../<project>-jobs_gen.json` (bundle only) | ONE dashboard for every job and cron job: runs (one per Kubernetes Job execution, however many pods it created; a Job recreated under the same name counts again), failures, duration and last run per job from the Kubernetes Job events, restarts, warnings, error logs. Jobs get no dashboard of their own |
| `deploy/observability/spec/*_gen.json` | `project_gen.json`, one `process-<workload>_gen.json` per long-running process and independent `alert-service-<svc>_gen.json` inputs |

A process's aliases across environments share a dashboard. Obsolete generated
service dashboards, spec parts and saved searches retire only when their bytes
still match the recorded checksum. Hand-owned overrides and modified generated
files stay on disk; workspace copies are not generator outputs.

Every dashboard has `service.name` and `deployment.environment.name` filters.
Process RPC procedure filters target metric RPC panels only; RPC service/method
filters target trace drilldowns. Runtime and workload panels are unaffected.
Metrics carry the canonical full `procedure`, not invented RPC attributes.

Optional generic viewer metadata: `sections: [{id, title, description}]` on a
dashboard, `section` on panels, and `panelIds` on filters. Empty/absent targets
retain the original global behavior; every non-empty target and section must be
declared. Sections are presentation groups, not authorization or implicit filter
scope. The console draws each section's `title` as a heading across the grid,
its `description` (optional, at most 500 bytes) under it, and the section's
panels below: the unsectioned panels first, then the sections in the order the
dashboard declares them, each section's panels in their declared order. A
viewer can hide a section from its heading.
HyperDX cannot target a filter to a subset of tiles, so it omits those dropdowns
rather than silently applying them globally.

Optional viewer defaults: `defaultRange` on a dashboard (`"7d"`: a number and
a unit of s, m, h or d, at most 30d) is the range it opens on when the viewer
picked none. A `sql` panel whose statement groups by a fixed bucket
(`toDate`, `toStartOfWeek`) rather than by `{step}` declares `minStep` (`"1d"`):
a range shorter than two such buckets draws one point, so the console widens
that panel's range to hold two and says so. `minStep` is also the bucket the
console names ("7-day buckets"): a `toMonday` week reads back as a Date, which
alone would be taken for a day, so a weekly panel declares `"7d"`. Prefer `{step}` in the statement
when the panel can follow the range. `defaultCompare` on a dashboard
(`"period"`, or `"release"`, which needs one selected environment) is the
comparison it opens with: a dashboard of headline figures declares `"period"`,
so each figure opens beside its change against the previous period. The viewer
can turn it off.

`scope` on a dashboard is one of `"project"` (the default), `"org"` or `"platform"`. `project` reads the environments selected within the route's project. `org` reads every project of the organization, still narrowed to the selected environments. `platform` says the signals are platform or infrastructure telemetry that belongs to no environment (a database, a message bus, a collector): it carries no `reliant.env.id`, so an environment filter would match nothing, and a reader drops that one predicate and nothing else. The scope is a statement about the data, not an access grant; who may read it, and from which organization's data, stays the reader's decision. Most projects never set it.

## What the panels match

Panels are keyed on what the runtime really emits, not on a convention:

- RPC edge: the otelconnect server interceptor opens a **server** span named
  `<proto package>.<Service>/<Method>` (no leading slash), e.g.
  `orders.v1.OrdersService/GetOrder`. Status is `Error` only for server faults
  (Internal, Unknown, Unavailable, DeadlineExceeded, Unimplemented); a client
  error such as NotFound is not an error span, so the error rate is a **server**
  error rate.
- Log lines carry `procedure` WITH a leading slash, which is how a service's
  logs are scoped (`LogAttributes['procedure']`).
- DB: the ORM's bun hook opens client spans with `db.system` and `db.operation`.
- Health: `rpc.server.calls`, `rpc.server.errors` (server error class only),
  `rpc.server.duration` (histogram seconds). These are unsampled; trace tables
  are drilldowns, not authoritative request totals.
- Runtime: `go.memory.used`, `go.memory.gc.goal`, `go.memory.allocated`,
  `go.goroutine.count`, scoped to the deployed process exactly once.
- Browser: spans from the HyperDX SDK carry the `rum.sessionId` resource
  attribute; `documentLoad`, `webvitals` and fetch/XHR spans (`component`).
  An uncaught error, an unhandled rejection and `console.error(err)` are
  **error spans** (`onerror`, `unhandledrejection`, `console.error`) with an
  `exception` event; `console.error("text")` is an error span with **no**
  exception event, so it is searchable but is neither an issue nor counted by
  `FrontendJSErrorSpike`. `webvitals` spans carry one metric each, as an
  attribute named for it (`lcp`, `inp`, `cls`, `fcp`, `ttfb`).

## Panel kinds

`number`, `line`, `table` and `search` are queries and draw anywhere. Three
more are drawn **only by the Reliant console**, from its own services rather
than a query over series, so they take no `series`, `columns` or `groupBy` and
read browser spans (`signal: traces`):

| kind | extra field | draws |
|---|---|---|
| `issues` | | grouped errors, new and regressed first |
| `sessions` | `hasError: true` narrows to sessions that hit an error | browser sessions, with a replay link when one was recorded |
| `funnel` | `funnel: {steps: [event, ...], window: "1h", by: "session"}` | product events (`track()` names) in order; 2 to 10 distinct steps, a window like `30m` / `1h` / `7d`, counted per `session` or `user` |

The HyperDX renderer **skips** them (HyperDX's own UI already plays replay and
searches spans), so a local `forge env up` stack shows the frontend dashboard
without them.

These kinds, and one field, are drawn by the console and have no HyperDX
equivalent, so HyperDX skips them too:

| kind / field | takes | draws |
|---|---|---|
| `bar` | `groupBy` (required), `series`, `limit` (default 10) | top-N bars: one group per `groupBy` value, the `limit` largest by the first series |
| `heatmap` | one series: `agg: count` plus a numeric `field` (`span.duration`); `signal` traces or logs | time across, value buckets up, each cell the number of events in it |
| `sql` | `sql`: one read-only SELECT; no `series`, `where` or `groupBy`; `signal` optional | the rows; a first `DateTime` column draws a time series |
| `postgres` | `postgres: {database, sql, draw?, time?, values?, group?}`; no `signal`, `series`, `sql`, `where` or `groupBy` | a live read-only query of one of your Postgres databases (`observability/dashboards/panels`) |
| `text` | `markdown`; nothing else | prose: a heading, what the dashboard is for, a runbook link |
| `browse` | `browse: {database, table, columns?, filters?, sort?, size?}`; nothing else | a saved data-browser view of one table |
| `release_health` | nothing (no `signal`) | the release scorecard: each environment's running release against the one it replaced, judged by release health (`forge obs check`'s rule and thresholds): the verdict, the findings, error rate, p95 and throughput before and after, new and regressed issues |
| `promotions` | `limit` (1 to 200, default 50); no `signal` | every promotion and rollback of the environments in scope over the range, newest first: release, commit, who promoted it, when |
| `delivery` | nothing (no `signal`) | the four DORA figures over the range from the release ledger: deployment frequency, lead time, change failure rate, time to restore |
| `link` on `table` / `bar` / `postgres` | `{database, table, column, fromField}` or `{database, table, row: true, fromFields}` | each row opens the data browser |
| `formula` on `line` / `number` | `"A / B * 100"`: series by position (A, B, ... J), numbers, `+ - * /`, parentheses | that one expression instead of the series; `x / 0` is 0, as in `ratio` |

The last three are the **delivery kinds**: drawn from the control plane's
release ledger and release-health verdict (`GetReleaseHealth`, `ListReleases`,
`GetDoraMetrics`), not from telemetry, so they carry no query. They read the
environments the viewer selected (every environment of the project when none
is) and, for `promotions` and `delivery`, the range; a service selection does
not narrow them. A control plane pinned to a forge older than the one that
added them cannot save a copy of a dashboard that uses them; it still shows the
release's dashboard.

`limit` (1 to 200) also keeps the top rows of a `table`. A `sql` statement runs
under the alert-rule guard and limits (one SELECT; no writes, DDL, `SETTINGS`,
`FORMAT`, `system.*` or outside table functions; a timeout and a row cap) as the
viewer's own read-only database user, and binds the dashboard's scope as
ClickHouse parameters: `{from:DateTime64(9)}`, `{to:DateTime64(9)}`,
`{step:UInt32}`, `{env_ids:Array(String)}`, `{envs:Array(String)}`,
`{services:Array(String)}`, and, when exactly one environment is in scope,
`{reliant_env_id:String}`, so an alert rule's query runs in a panel as written
(over any other scope a statement that uses it is refused: choose one
environment).

A **toggle filter** is an on/off switch a `sql` panel reads as a Bool
parameter named by its id: `{"id": "include_internal", "kind": "toggle",
"label": "Include internal users", "default": false}` binds
`{include_internal:Bool}`, so `WHERE {include_internal:Bool} OR UserId NOT IN
(...)` hides internal users until the viewer turns it on. The id must match
`^[a-z][a-z0-9_]{0,31}$` and not name a built-in parameter; a toggle takes no
`field`, `signal` or `panelIds`, and structured panels ignore it. A reader binds
every toggle the dashboard declares (its `default` until the viewer sets it:
`dashspec.Dashboard.ToggleValues` into `obsquery.Scope.Toggles`), so the
statement may rely on it. Only a reader that knows toggles binds them: do not
ship a panel that reads one to a control plane older than the forge that added
them.

Postgres panels (a live read-only query of your own database), `link`,
`browse`, `text` panels (Markdown), `display` (area, stacked, bars, pie, donut, gauge,
funnel and heatmap pictures of the same query), palette colours per series (`color`,
`colors`), sparklines on sql figures (`trendSql`) and data-dependent subtitles (`subtitleSql`) are in `observability/dashboards/panels`.

A `table` or `number` series may carry `thresholds: {good, poor}`
to grade its value like Core Web Vitals do; renderers that cannot colour ignore
it. The frontend dashboard's **Web vitals by route** table uses it for the p75
of LCP, INP and CLS, and **JS errors by release** splits the error spans by
`service.version` (the build id).

## Product events

A **product event** is a named thing a user did (`project_created`): one INFO log
record that the hosted platform keeps in the per-environment `product_events`
table, read with `sql` and `funnel` panels. Generated CRUD emits
`<entity>_created|_updated|_deleted` automatically (`signals.product_events =
False` turns them off). The contract, `observe.Track`, the browser API, the
automatic events and their cost, retention and example panels:
`observability/product-events`.

## Overriding

Never edit a `*_gen.json`: forge rewrites it and refuses a hand-edit as drift.
Copy `x_gen.json` to `x.json`, give it a new `name`, edit it. While `x.json`
exists forge stops writing (and removes a pristine) `x_gen.json`. Any other
`*.json` in the directory is yours and is never touched.

## Dashboards in the release

`forge env build <env> --release <v>` puts the dashboards into the release bundle, so the Reliant console shows the set that belongs to the release that is running (and a rollback shows the older one):

| In the bundle                                      | What                                                                                                                        |
| -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `observability/dashboards/<project>-<id>_gen.json` | each dashboard of the spec, plus `<project>-custom-metrics_gen.json` drawn from the build's metrics schema                   |
| `observability/dashboards/<name>.json`             | a dashboard you own                                                                                                         |
| `observability/metrics-schema.json`                | the schema, `forge.metrics/v1`                                                                                              |

They ride in the manifests layer, outside every `manifests/<cluster>/` tree, so nothing is applied from them.

A file you own is one dashboard object in the spec vocabulary (an `id`, a `title`, `filters`, `annotations` and a `panels` array; the shape of a `dashboard` in `spec/process-<workload>_gen.json`). Name it like a generated dashboard to replace that one: `shop-overview.json` replaces `shop-overview_gen.json`. A file with `tiles` is HyperDX's format; it is for the local stack, ships nowhere and replaces nothing. Ad-hoc console edits are saved as code by writing the dashboard JSON here and committing it.

Every file is validated at the cut, and `forge obs dashboards check` runs the same checks and lists what would ship. Errors read `deploy/observability/dashboards/x.json:12:7: panels[2].kind: "cube" is not one of: number, line, table, search, bar, heatmap, sql, issues, sessions, funnel, postgres, text, browse, release_health, promotions, delivery`.

The file checks cannot know what your telemetry holds. `forge obs dashboards check --against <env>` also looks up every metrics panel series in that env over `--since` (24h): a `metricType` that is not the kind the metric is stored as fails the check, and a metric with no data is listed (a misspelt name, one the collector drops or renames, such as the filter processor's `otelcol_processor_filter_logs.filtered`, or a counter that only exists once something fails). `--strict` fails on those too. In the console a series with no data draws an empty panel with a `metric_absent` note, never an error.

`annotations: [{"source": "releases"}]` on a dashboard asks the console to draw a marker for every promotion on its time-series panels. Generated dashboards declare it.

The _Workloads_ dashboard (CPU/memory against requests and limits, restarts and exit reason, image versions, Kubernetes events) and the _Releases_ dashboard are generated for every project. They read node-derived and release data that a local `forge env up` does not have, so they ship in the spec and the bundle and are not written to `deploy/observability/dashboards/`.

The _Releases_ dashboard (id `releases`) is what a team opens after shipping, over the last 7 days by default. _Latest release_: a `release_health` panel, each environment's running release judged against the one before it, with the same verdict a release's Health tab and `forge obs check` give (good, regressed, or not enough data). _Delivery_: the DORA figures (`delivery`) and the promotion timeline across environments, rollbacks included (`promotions`). _Adoption_: the share of backend requests and of browser sessions each `service.version` served, per bucket, so a rollout reads as one band replacing another. _Health by release_: error rate, p95 and requests by version (with deploy markers), new issues by the release that first raised them (at least `new_issue_min_events`, 3 by default, first seen in the 30 days before the end of the range; a browser issue is its symbolicated stack's fingerprint, so one error across two builds is one issue), a side-by-side table of every backend version, and crash-free browser sessions by frontend version (sessions with no uncaught exception, unhandled rejection or recorded exception). Its sql panels count what release health counts: tail-sampling-weighted server spans, errors that are not cancellations, latency without streaming RPCs (`obsquery.SpanWeightSQL`, `SpanErrorSQL`, `SpanServerSQL`, `SpanStreamSQL`, for your own statements too). The dashboard is the cross-release trend; one release's full scorecard is its Health tab in the console.

So are the built-in product dashboards, _Product overview_, _Users_, _Product_ and _Acquisition_ (ids `product-overview`, `users`, `product`, `acquisition`; bundle files `<project>-users_gen.json` …), all `sql` panels over `product_events`, which the local ClickStack has no table for, and the Overview's _Traffic_ and _Users_ sections, which HyperDX leaves out (the existing overview panels form its first section, _Health_). _Product_ declares `replaces: ["usage"]`: it supersedes the generated _Product usage_ dashboard of earlier forge releases, whose stars and copies move to it. What each panel counts and how to extend (`forge.Analytics`), override (`<project>-users.json`) or drop them (`dashboards = False`): `observability/product-analytics`. Where the events come from: `observability/product-events`.

## Alerts

Dashboards embed no alerts (HyperDX 2.40 validates an alert declared in a provisioned file and never evaluates it, hyperdx PR #3233). Alerting is declared in KCL instead: `forge.AlertRule`, with generated defaults (telemetry, customer-metadata and platform) in `alert-defaults_gen.json`, and each service's independent `spec/alert-service-<svc>_gen.json`. Depth: `observability/alerts`.

## The seam: spec, then renderer

`internal/obsdash` builds a `Spec` (dashboards > panels > series with a signal,
an aggregate and predicates on OpenTelemetry field names; no ClickHouse or
HyperDX names) and renders it. `RenderHyperDX` is one renderer; the Reliant
console draws the same Spec with uPlot. A hosted deliverer pushes the rendered
JSON through the HyperDX API.

Tiles name their source (`Logs`, `Traces`, `Metrics`). The file provisioner
stores that verbatim but the UI resolves sources by random per-database id, so
the delivery step swaps names for ids: locally the compose entrypoint does it
(and upserts the saved searches); through the API, use `GET /api/v2/sources`.

Files in this skill

  • SKILL.md22.1 KB
  • panels/SKILL.md12.2 KB

Attribution

Is this your skill, or is something wrong with this listing? Request removal or report an issue. Author removals are honored within 72 hours.

View all in development →

Comments

Loading comments…

Newsletter

Get the weekly list of safe new skills, and the ones we pulled.