# Dashboards

A dashboard is a set of widgets over one time range. Every widget's data comes from one
request (`GET /orgs/:org/dashboards/:id/data`), which runs the whole set on the server. A
widget that fails shows its own error, and the rest of the board still draws. Widgets read
denormalised counters, rollups, spans and logs. They never read the raw error-event table.

## Templates

**New dashboard** can start from a template instead of a blank board. A template is a
fixed, versioned board defined in Bucker's code and built only from the widgets listed
below. Picking one makes an ordinary dashboard that is yours: rename it, move its tiles,
add or remove widgets. Later changes to the template do not change your copy. The board
records which template and version it came from (`templateId`, `templateVersion`).

| Template | What it shows |
| --- | --- |
| Project health | new issues, top issues by users, crash-free sessions, alert volume |
| Release health | crash-free sessions overall and by environment, operating system and browser; regressed issues |
| AI spend and agents | AI spend by kind; model calls and p95 call duration by model |
| Ingest and quota | accepted and dropped events, and why |
| Web vitals | p75 LCP, INP, CLS, FCP and TTFB from real page loads, p75 LCP over time, and p75 LCP, INP and CLS per page; needs `@bucker/browser/web-vitals` ([sdk-browser.md](sdk-browser.md#web-vitals)) |
| Queries | slowest queries (p95), time spent and frequency per query, query p95 over time |
| Outbound HTTP | calls, p95 and failed calls per domain |
| Caches and queues | cache hits against misses; publish and process p95 per message destination |
| Endpoints and services | slowest, busiest and failing endpoints; the service map |

Web vitals and the four after it are **insights**, and each is for one project: the dialog asks which.
They read span attributes, so they fill in once a project sends traces (OTel, or a Sentry
SDK with tracing on).

### Attributes Bucker adds to spans

When a span is stored, Bucker adds these attributes so the insight boards can group by
them. It never replaces one your SDK already set.

| Attribute | On | Value |
| --- | --- | --- |
| `bucker.db.query` | any span with `db.query.text` or `db.statement` | the statement with literals replaced by `?` and `IN (…)` lists folded, so `id = 7` and `id = 8` are one query |
| `bucker.http.domain` | client spans with an HTTP method | the host called, from `server.address` or the URL |
| `bucker.http.path` | the same | the path, with ids, UUIDs, hashes and tokens replaced by `:id`, `:uuid`, `:hash`, `:token` |
| `bucker.endpoint` | server spans with an HTTP method | `METHOD route`, from `http.route`, or else the normalised path |

The statement is normalised after your scrubbing rules run, so a value a rule removed is
never put back. Caches use `cache.hit`, and queues use `messaging.destination.name` with
the span kind (`producer` or `consumer`), as OpenTelemetry defines them. You can use all
of these in Explore as well.

An equality filter on any of them — `bucker.endpoint:"GET /checkout"`, or any other span
attribute — is answered through an index on span attributes, so filtering a busy
project's spans to one endpoint or one query does not read every span in the window.

### Service map

The **Service map** widget lists every pair of services where a span from one is the parent
of a span from the other (`service.name` on the resource). Each row has the caller, the
callee, the number of calls, their p95 duration and how many failed. It reads the newest
50,000 child spans in the range, and says so when it hits that limit.

Bucker does not create dashboards for you. A new organization's Dashboards page is empty
and offers **Start from a template**.

## Filters

The board toolbar has four controls besides the dashboard picker:

- **Range**: the last 24 hours, 7 days or 30 days.
- **Environment**: one or more environments. This is the same `?env=` the context strip
  carries, so the choice stays with you when you go from a board to Issues or Explore.
- **Release**: one release, or all of them.
- **Refresh**: off, or every 1, 5 or 15 minutes. A board in a hidden tab does not poll.

A widget says which filters it can apply (`GET /dashboards/widget-types` lists them per
type):

| Widget | Environment | Release |
| --- | --- | --- |
| Explore query (spans, logs) | yes | yes |
| Crash-free rate | yes | yes |
| New issues, Top issues, Alert volume, Ingest outcomes, AI spend, Note | no | no |

If a filter is set and a widget cannot apply it, the widget shows a note saying so. It
does not draw the unfiltered number as if it were filtered. The filters can only narrow a
widget: a widget pinned to `staging` on a board filtered to `production` shows nothing,
because nothing is in both.

## Deploy and release markers

Every time series on a board has a rule for each deploy (solid) and each new release
(dashed) in the range. The rules cover the projects the board covers. When the board is
filtered by environment, only deploys to those environments are drawn. Each rule also
appears as a line of text under the chart, with its version, environment and time.

## Layout

**Edit layout** turns the board into a list of tiles. Each tile has four arrow buttons
(up, down, earlier, later) and a **Full width** toggle. A half-width tile takes one of
the two columns; a full-width tile takes both. You can also drag a tile onto another one,
but everything dragging can do, the buttons can do too. **Save layout** saves the order
and the widths in one request.

## Revisions, archive and the agent reads

**Every save is a revision.** Creating a board writes revision 1, and every later save (the layout
editor, a rename, a widget edit, a change to the notes or the variables) writes the next one with
who made it (`human`, `agent`, `client` or `system`) and what changed: the widgets added, removed,
moved and edited, named by their stable key, and which board fields changed. A save that changes
nothing writes nothing. **History** on a board opens the timeline; **Restore** on a revision makes
a *new* revision that copies it, so nothing in the history is rewritten. A board keeps its 500 most
recent revisions in full; older ones keep their summary and digest and can no longer be restored.

**A widget keeps its id.** Widgets have a stable key (a ULID) that survives every save. The editor
still sends the whole widget list with no ids, and each widget is matched to the one it was by its
key, then its id, then its type, title and settings, so a layout-only save changes no widget id and
a widget's history (its query-log trail) does not split at each save. A board of 24 widgets saves in
one transaction.

**Archive, not delete.** **Archive** hides a board from the list at once; it is still readable by
its link, cannot be edited, and is removed after 30 days. An owner brings it back (as a draft) with
`POST …/unarchive`. A *permanent* delete is `DELETE`, which is a person's act and an organization
owner's only; an agent or a connected client is refused. A **draft** board is visible to its author
and to organization admins only.

**Variables** (at most five) and **notes** are part of the board's spec and so part of every
revision.

### Reading a board over MCP

Three read-only tools return a board without running it. They need `project:read` (and, for
`widget_data_get`, `event:read`), they are in the `metrics` toolset, and a board or widget you cannot
read is *not found*, never listed or counted.

| Tool | Returns |
| --- | --- |
| `dashboards_list` | id, name, description, visibility, revision and widget count; `kind: notebook` and `include: widget_types` are answered `notAvailable` |
| `dashboard_get` | the spec (title, scope, variables, layout, widgets by key, notes), its digest and the last change's summary; `include: revisions` adds the history with a cursor; no widget data |
| `widget_data_get` | one widget's data, by its key, with `bounds` (`scanned`, `scanTruncated`, `groupsTruncated`, `groupCount`) |

Titles, descriptions, notes, variables and widget settings are written by members and are served as
untrusted text: scrubbed, scanned for instructions and capped.

## API

| Call | What it does |
| --- | --- |
| `GET /orgs/:org/dashboards/:id/data?days=&environment=a,b&release=` | runs every widget; the response has `filters`, `markers`, and for each widget its `width` and `filters` (`applied`, `ignored` or `none`) |
| `PATCH /orgs/:org/dashboards/:id` with `widgets: [{ type, title, config, position, width }]` | saves the widget set as a diff by widget key (an optional `key` or `id` names the widget); `width` is `1` (half) or `2` (full). Also takes `notes` and `variables` |
| `GET /orgs/:org/dashboards/:id/revisions?before=&limit=` | the history, newest first, with each revision's diff; `GET …/revisions/:n` adds its spec |
| `POST /orgs/:org/dashboards/:id/revisions/:n/restore` | restores revision `n` as a new revision |
| `PUT /orgs/:org/dashboards/:id/visibility` with `{ visibility: draft \| shared }` | shares a draft or makes a board a draft |
| `POST /orgs/:org/dashboards/:id/archive`, `…/unarchive` | archive (removed after 30 days); unarchive is a person's act and returns a draft |
| `DELETE /orgs/:org/dashboards/:id` | permanent delete; a person who owns the organization |
| `GET /dashboards/templates` | the templates, each with its id, version, scope and widgets |
| `POST /orgs/:org/dashboards` with `{ templateId, name?, projectSlug? }` | clones a template; the name defaults to the template's, and a per-project template needs `projectSlug` |
| `GET /dashboards/widget-types` | each widget type with the tables it reads and the filters it can apply |
