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:

ModeHoldsHow it shows them
autoWidgetsOn 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.
customWidgetsEach widget in the cell it states, on a grid of 24 columns.
rowsGroupsOne under another. Each group has a header that collapses it.
tabsGroupsAs 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:

yaml
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 group of charts in rows mode

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.

The menu of a table widget with Link grid

In YAML, the grid key of a table widget holds the linked grid:

yaml
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.

The list of dashboard templates

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:

yaml
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:

MetricDescription
uptrace_tracing_spansNumber of spans and their duration (excluding events and logs)
uptrace_tracing_eventsNumber of events (excluding spans and logs)
uptrace_tracing_logsNumber of logs (excluding spans and events)
uptrace_service_graph_client_durationRequest duration between two nodes as seen from the client
uptrace_service_graph_server_durationRequest duration between two nodes as seen from the server
uptrace_service_graph_failed_requestsTotal count of failed requests between two nodes
uptrace_billing_sampled_bytesNumber of sampled bytes per project
uptrace_billing_sampled_spansNumber of sampled spans and logs per project
uptrace_billing_dropped_spansNumber of dropped spans and logs per project
uptrace_billing_timeseriesNumber of active timeseries per project