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) |
| 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 |