Dashboards and visualizations

A dashboard is a combination of charts, visualization components, template variables and drill-down actions over one screen, so a set of related metrics is watched together. Reports (the saved searches from search-analysis.md) are added to dashboards, and dashboards are what an operator leaves up.

---

The dashboard list. Dashboards installed by an app appear here alongside the ones you create; the App column says which is which. Captured September 30, 2026.

Creating a dashboard

Three routes in:

1. From a search — run a search that returns a table (stats, timechart, top …), open the Visualization tab, pick a chart type, and choose Add to dashboard. The dialog adds the chart to an existing dashboard, or — with Create Dashboard at the top of its list — creates one in the same step: pick the app, name the dashboard, give the panel a title. The panel keeps the query and the chart type. Run end to end in September 2026: a stats count() as n by service bar chart went onto a new dashboard, and after a full reload the panel showed the same three bars (12, 8, 5) as the search.
2. From a report — save a configured search/analysis report and add it to a dashboard.
3. From the dashboard list — Dashboards → Dashboard, Add dashboard, name and description.

A dashboard built the first way, one search at a time, over the checkout incident: payments-gateway and checkout-api fail together from about 14:02, while the wait for a ledger-db connection sits above five seconds. The time range in the bar above the panels applies to every panel. Captured September 30, 2026.

The dashboard editor then places charts. Chart groups organize a screen — create, edit (rename, background color), delete a group (with or without its contents).

Chart configuration

Each chart is a visualization of a query:

• Query — the SonQL statement (see search-sonql-reference.md) or an interactive configuration.
• Chart type — the visualization library: single-value, line, area, bar, pie, table, histogram, heat map, map, and the rest of the catalog.
• Template variables — named placeholders ($var$) bound to a query or a field list, so one dashboard switches context (environment, service, repo) without editing every chart.
• Drill-down — a chart can jump to a search, report or URL on interaction.

Configuring a chart interactively

A chart’s data can be configured without writing SonQL, in the Data Configuration panel of the visualization:

• Metrics — the aggregations the chart plots: field count, distinct count, sum, average, median, maximum, minimum. Average/sum/max/min accept a formula, e.g. _value * (60 * 60), and a display name (so a shared chart reads clearly).
• Grouping fields — how the data is aggregated. A time field groups into intervals (automatic or a value you set); with several grouping fields you choose which is the X-axis and which becomes multiple series.
• Filter — narrow the aggregated results; only rows meeting the filter are charted.
• Sort — the sort metric and direction (ascending/descending).
• Limit — how many rows the chart may show.

A SonQL search (e.g. search2 repo="default" | stats count() as count by _time) switches to the Visualization tab as a line chart, which can then be restyled — chart type, fonts, stacking, axes — the same interactive builder underneath.

Dashboard operations

action	what it does
Refresh	auto-refresh interval for all charts on the screen
Time range	switch the window all charts query
Display style	black or white background
Full screen	presentation mode
Export	export the dashboard as profile / image / PDF
Chart download	per-chart data export as JSON, CSV, TSV (the download icon on a chart)

Editing an existing chart exports its configuration as a SonQL search statement (exportxmltooltip), so a configured chart becomes a query — the reverse of building a chart from a query.

Report subscriptions

A subscription emails a dashboard or a report on a schedule, as an Excel workbook with one sheet per chart — each sheet is that chart’s query result over the window.

• Create one from a dashboard with ⋯ → Subscription → Create task, or from a report’s header. Dashboards → Subscription Tasks lists them; Running Record Management shows every run and, for a failed one, why.
• Schedule — every minute, hour, day, week, month, quarter or year, or a crontab. Send Direct sends once, now.
• Window — Time Limit sets the data window. Left empty, the dashboard’s own window is used; in a report, each dashboard keeps its own window and the report’s chart blocks use the report’s. Times in the workbook are UTC.
• Delivery is email through an SMTP server added under Configure → Notification Settings. Leave the password empty for a relay that takes no login. TLS upgrades the connection with STARTTLS (usually port 587); SSL is TLS from the first byte (usually 465). With either, the server’s certificate must be trusted and must name the host you entered, and with TLS a server that does not offer STARTTLS is refused rather than sent the mail in plain text — see TLS for alert delivery.
• A report sends the charts of each dashboard it holds, then its own chart blocks. Markdown blocks carry no data and are left out.
• Not a picture. The attachment is the data. A PDF or image of a dashboard is a manual export: ⋯ → Export PDF or Export Image.