Dashboards
Uptrace dashboards let you build custom visualizations from spans, events, logs, and metrics using a Prometheus-inspired query language. Dashboards can be authored in the graphical UI or defined as YAML files — both produce the same result and can be used together.
The video fixes seven dashboards with layout problems: the height and width of stats and tables, rows and tabs, a grid for each row, a Custom grid, a change that History brings back, and a table that opens a grid for each row.
To create a dashboard, go to Metrics → Dashboards and click New dashboard.
Layout
A dashboard has one layout. The root of the layout holds either widgets or groups, never both:
- A widget shows the result of a query: a chart, a table, a stat, a gauge, a pie, a heatmap, or a text.
- A group holds widgets, or other groups, under a title.
The root and each group arrange what they hold in one of four modes:
| Mode | Holds | How it shows them |
|---|---|---|
auto | Widgets | On a grid of columns. Each widget takes one cell or the full width, and all grid rows have the same height. A narrow screen shows fewer columns. |
custom | Widgets | Each widget in the cell it states, on a grid of 24 columns. |
rows | Groups | One under another. Each group has a header that collapses it. |
tabs | Groups | As tabs. The dashboard shows one group at a time. |
To change the layout, click Edit on the dashboard. Edit mode is a draft: Save stores all changes as one change, and Cancel discards them. See Layout and editing for each task: group widgets into rows and tabs, move widgets, and set the grid.
In YAML, the layout key holds the root. Groups of charts in rows mode look like this:
layout:
items:
- type: group
title: General
items:
- title: CPU utilization
metrics:
- system_cpu_utilization as $cpu_util
query:
- avg($cpu_util)
- title: CPU time
metrics:
- system_cpu_time as $cpu_time
query:
- perMin(sum($cpu_time)) as cpu_time group by state
stack: all

A root that holds groups is in rows mode unless it states another mode. Add mode: tabs to show the groups as tabs. See Layout in the YAML reference for all layout fields.
Table widgets and linked grids
A table widget aggregates data per grouping dimension — for example, per host or per service. A table widget in the root of the layout can link a grid: a layout of its own, with widgets and groups. The button at the start of a row opens the grid in a dialog, filtered to the group by values of that row. The table acts as a variable selector, so the grid needs no variable dropdowns.
To create the grid, open the menu of the table widget and click Link grid. When the grid exists, Open grid opens it in the same tab, and you edit it as you edit the dashboard. Back returns to the dashboard. Only a table widget in the root links a grid. A table widget in a grid does not.

In YAML, the grid key of a table widget holds the linked grid:
layout:
items:
- type: table
title: Hosts
metrics:
- system_cpu_utilization as $cpu_util
- system_memory_utilization as $mem_util
query:
- group by host_name
- avg($cpu_util) as cpu_util
- avg($mem_util) as mem_util
columns:
cpu_util: { unit: utilization }
mem_util: { unit: utilization }
grid:
items:
- type: group
title: General
items:
- title: CPU utilization
metrics:
- system_cpu_utilization as $cpu_util
query:
- avg($cpu_util)
A dashboard does not need a table. Leave it out, and put the charts directly in the root.
Dashboards from earlier releases
Earlier releases showed a dashboard as two tabs, Table and Grid. Uptrace converts each such dashboard: the Table tab becomes the root, the table becomes a table widget at the end of the root, and the Grid tab becomes the grid that this table widget links. A saved link to a Table or Grid tab opens the same contents in the new layout. Templates in the earlier YAML format still import. See Earlier template formats.
Dashboard templates
Uptrace ships with pre-built YAML templates for popular OpenTelemetry instrumentations and exporters:
- Infrastructure: host metrics, Prometheus node_exporter, Kubernetes, Docker, AWS, NGINX, and HTTP checks.
- Databases and messaging: PostgreSQL, MySQL, Redis, HikariCP connection pools, Kafka brokers, and Kafka client producer, consumer, partition, and broker dashboards.
- Runtimes: Go, Node.js, Python, JVM, .NET and ASP.NET Core, and PHP-FPM.
- OpenTelemetry pipeline: the OpenTelemetry Collector, SDK self-metrics, and span metrics.
- Application signals: HTTP and RPC calls, GenAI model token usage, and OpenFeature feature flags.
You can find the full list on GitHub.
When Uptrace receives new metrics, it checks available templates and automatically creates dashboards for matching metrics — no manual setup required.
To see all templates, go to Dashboards → Templates. The tabs at the top sort them by status: Ready templates have data in the project, No data templates have none yet, and Installed templates already have a dashboard.

You can import and export dashboard templates as YAML through the Uptrace UI. To share dashboards with the community, open a pull request on GitHub.
Templates can also bundle metric monitors so dashboards and their alerts ship as a single file:
metric_monitors:
- key: cpu_usage
name: CPU usage
type: threshold
metrics:
- system_cpu_load_average_15m as $load_avg_15m
- system_cpu_time as $cpu_time
query:
- avg($load_avg_15m) / uniq($cpu_time, cpu) as cpu_util
- group by host_name
column:
name: cpu_util
unit: utilization
max_value: 3
num_eval_points: 10
Each bundled monitor needs a key, and type selects the detector: threshold, anomaly, outlier, or forecast. See metric monitors in the YAML reference.
System metrics
Uptrace provides built-in metrics under the uptrace_ prefix for accessing internal system data:
| Metric | Description |
|---|---|
uptrace_tracing_spans | Number of spans and their duration (excluding events and logs) |
uptrace_tracing_events | Number of events (excluding spans and logs) |
uptrace_tracing_logs | Number of logs (excluding spans and events) |
uptrace_service_graph_client_duration | Request duration between two nodes as seen from the client |
uptrace_service_graph_server_duration | Request duration between two nodes as seen from the server |
uptrace_service_graph_failed_requests | Total count of failed requests between two nodes |
uptrace_billing_sampled_bytes | Number of sampled bytes per project |
uptrace_billing_sampled_spans | Number of sampled spans and logs per project |
uptrace_billing_dropped_spans | Number of dropped spans and logs per project |
uptrace_billing_timeseries | Number of active timeseries per project |
Related
- Layout and editing — edit mode, rows and tabs, moving widgets, the grid
- Dashboard YAML Templates — full YAML schema reference
- Querying metrics — MQL query language for metrics
- Observability as Code — manage dashboards as version-controlled YAML files
- MCP Server — create and update dashboards from AI assistants