Dashboards
A dashboard is a named collection of widgets pinned to a layout, with a shared global time range. Build them for war-rooms during incidents, for the wall TV at standup, or for the CTO’s daily dashboard refresh.
When to use dashboards
Section titled “When to use dashboards”- One canonical “is everything OK?” view per service.
- Incident war-rooms — pin every relevant signal in one place.
- Executive summaries — top-line business KPIs from your metric pipeline.
When NOT to use them
Section titled “When NOT to use them”- For ad-hoc exploration — use the per-pillar Explorers (Logs, Metrics, Traces).
- For alerting — alerts live in the incident management layer, not on a chart.
Anatomy
Section titled “Anatomy”| Field | Description |
|---|---|
name | Required, displayed at the top. |
description | Optional context. |
global_time_range | Object: {type: "relative", value: "1h"} or {type: "absolute", from: ..., to: ...}. Per-widget overrides allowed. |
auto_refresh_seconds | Optional polling interval. Common values: 30, 60, 300. |
widgets[] | Array of DashboardWidgets. |
Widget types
Section titled “Widget types”| Type | Renders |
|---|---|
timeseries | Line / area chart over time. Most common for metrics. |
stat | Single big number (current value, latest p99, count). |
table | Tabular grid (group-by results, top-N lists). |
log_stream | Live-tailing log feed with filters. |
monitor_status | Status grid for a list of monitors. |
text | Markdown text — annotations, runbook links, headers. |
Data sources
Section titled “Data sources”| Source | Use |
|---|---|
metrics | Time-series metric queries. |
logs | Log queries (counts, top values, streams). |
traces | Trace counts, latency percentiles. |
uptime | Monitor status and uptime percentages. |
rum | Web vitals, session counts, error rates. |
none | For text widgets that don’t query anything. |
Widget layout
Section titled “Widget layout”Each widget has a layout: {x, y, w, h} on a 12-column grid. Default is {x: 0, y: 0, w: 6, h: 4} — half-width, 4 rows tall. Drag to reorder in the dashboard editor.
Time range hierarchy
Section titled “Time range hierarchy”- The dashboard has a
global_time_range. - Each widget can override with
time_range_override(e.g. for a “last 7 days” stat on an otherwise “last 1 hour” dashboard). - The user can change the global range at the top of the page; widget overrides ignore it.
Auto-refresh
Section titled “Auto-refresh”Set auto_refresh_seconds to poll every N seconds. Useful for war-room dashboards on a wall TV. Don’t set it on dashboards that drive expensive aggregations — refreshing every 30 seconds across 20 metric widgets is real load on ClickHouse.
See also
Section titled “See also” Quickstart Build your first dashboard with metrics and logs widgets.
Widget reference Every widget type and its config shape.
Metrics The most common dashboard data source.