Skip to content
bucker

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