Creating dashboards

Telemetry dashboards combine charts, tables, and notes in one team view. Pin results from Explore or Query, then arrange widgets and add notes. You can also create dashboards through the API.

What a dashboard includes

• A dashboard is a named page for related metrics.
• Each widget contains a saved chart, table, section header, or note.
• Chart and table widgets use an Explore configuration or a Query result.
• In Edit mode, drag widgets to move them and resize them to fit.

Step 1: create a dashboard

You can create dashboards in three ways:

1. In the left sidebar, open Dashboards menu and click New Dashboard.
2. From a completed Explore result, click Create starter dashboard & save if no dashboard exists; otherwise save to the named dashboard.
3. Call POST /dashboard with an API key that has read-and-write scope.

Step 2: add widgets from explore

1. Open a table and go to the Explore tab.
2. Choose:
   • graph type, Samples, Table, Line, Bar, or Stacked Area
   • aggregation and granularity for chart views
   • time range, filters, and group by fields
3. Click Run.
4. Click Save to Getting Started (or the named dashboard), or Save this result in the inline prompt. This saves the result with a default widget title.
5. If multiple dashboards exist, use Choose dashboard to select another destination and enter a widget title.

After a result is saved, an eligible time chart can offer an inline monitoring prompt:

The save action can appear in the result toolbar or an inline Save this result prompt. Quick-save uses a default widget title.

Telemetry stores the full Explore state, so the widget stays consistent with the chart/table you pinned.

Step 3: add widgets from query

1. Open a saved query or draft query.
2. Run the query and switch to either Results or Chart.
3. Click the named dashboard save button or Save this result.
4. For a different destination or widget title, use Choose dashboard when multiple dashboards exist.

Use this path when you want fully custom SQL rather than Explore-generated SQL.

Step 4: arrange and maintain your dashboard

1. Open /team/{team}/dashboard/{dashboard-slug}.
2. Click Edit.
3. Use Add Component to insert:
   • Section Header blocks for grouping related widgets under a shared title and description
   • Free Text blocks for markdown notes, links, and runbook-style context
4. Drag widgets by the handle, resize as needed, and remove widgets with X.
5. Click Done when layout changes look right.

You can also rename, copy URL, or delete dashboards from the dashboard actions menu in the sidebar.

Programmatic dashboard creation

Use the Dashboard API when you want to provision dashboards from code, seed new environments, or generate dashboards during onboarding.

The API can:

• create an empty dashboard shell
• create a dashboard and its first widgets in one request
• create both SQL-backed query widgets and Explore-backed widgets
• create section headers and free-text widgets for dashboard organization

Inline interactive examples

SELECT
  date_trunc('hour', timestamp_utc) AS hour,
  100.0 * SUM(CASE WHEN status_code >= 500 THEN 1 ELSE 0 END) / COUNT(*) AS error_rate_pct
FROM
  http_logs
WHERE
  timestamp_utc >= now() - INTERVAL '7 days'
GROUP BY
  hour
ORDER BY
  hour ASC

SELECT
  endpoint,
  AVG(duration_ms) AS avg_duration_ms
FROM
  http_logs
WHERE
  timestamp_utc >= now() - INTERVAL '24 hours'
GROUP BY
  endpoint
ORDER BY
  avg_duration_ms DESC
LIMIT 15

SELECT
  timestamp_utc,
  service,
  endpoint,
  status_code,
  error_message
FROM
  http_logs
WHERE
  status_code >= 500
  AND timestamp_utc >= now() - INTERVAL '24 hours'
ORDER BY
  timestamp_utc DESC
LIMIT 200

Dashboard design tips

• Keep one primary question per widget. For example, "Are error rates rising?"
• Mix trend widgets with drilldown tables.
• Add section headers before major groups so dashboards stay scannable as they grow.
• Use free-text notes for alerting context, runbook links, or definitions teammates need while debugging.
• Use clear widget titles so teammates can scan the page quickly.
• Start with 4-8 widgets; add more only when each one adds a new decision signal.