# Dashboards

> Build custom dashboards from spans, events, logs, and metrics using a graphical UI or YAML. Table and grid layouts, PromQL-style expressions, and auto-activating templates.

Uptrace dashboards let you build custom visualizations from spans, events, logs, and metrics using a Prometheus-inspired [query language](/features/metrics/querying). Dashboards can be authored in the graphical UI or defined as YAML files — both produce the same result and can be used together.

<video autoPlay="true" loop="true" muted="true" playsInline="true">
<source src="/features/metrics/metric-dashboard-overview.mp4" type="video/mp4" />
</video>

To create a dashboard, go to **Metrics → Dashboards** and click **New dashboard**.

## Table and grid

Uptrace uses two complementary dashboard types together:

### Table dashboard

A **table dashboard** aggregates data per grouping dimension — for example, per host or per service. Each row links to the grid dashboard filtered to that row's values, acting as a variable selector without requiring explicit variable dropdowns.

<video autoPlay="true" loop="true" muted="true" playsInline="true">
<source src="/features/metrics/metric-tableview.mp4" type="video/mp4" />
</video>

```yaml
table:
  metrics:
    - system_cpu_utilization as $cpu_util
    - system_memory_utilization as $mem_util
    - system_memory_usage as $mem_usage
  query:
    - group by host_name
    - avg($cpu_util) as cpu_util
    - avg($mem_util) as mem_util
    - sum($mem_usage{state="used"}) as mem_used
  columns:
    cpu_util: { unit: utilization }
    mem_util: { unit: utilization }
```

![Table dashboard](/features/dashboards/table.png)

### Grid dashboard

A **grid dashboard** is a classic layout of time-series charts organized in collapsible rows — similar to Grafana.

<video autoPlay="true" loop="true" muted="true" playsInline="true">
<source src="/video/product/metrics/metric-dashboards.mp4" type="video/mp4" />
</video>

```yaml
grid_sections:
  - 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
        chart: stacked-area
```

![Grid dashboard](/features/dashboards/grid.png)

Start with a table dashboard and add a grid later. A grid dashboard can be used standalone if no table is needed — just leave the `table` section empty.

## Dashboard templates

Uptrace ships with pre-built YAML templates for popular OpenTelemetry instrumentations: [host metrics](/opentelemetry/collector/host-metrics), [PostgreSQL](/guides/opentelemetry-postgresql), [MySQL](/guides/opentelemetry-mysql), Kubernetes, Redis, .NET, and many more. You can find the full list [on GitHub](https://github.com/uptrace/uptrace/tree/master/config/dashboard-templates).

When Uptrace receives new metrics, it checks available templates and automatically creates dashboards for matching metrics — no manual setup required.

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](https://github.com/uptrace/uptrace).

Templates can also bundle metric monitors so dashboards and their alerts ship as a single file:

```yaml
monitors:
  - name: CPU usage
    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
    detector:
      type: manual
      max_value: 3
    num_eval_points: 10
```

## System metrics

Uptrace provides built-in metrics under the `uptrace_` prefix for accessing internal system data:

<table>
<thead>
  <tr>
    <th>
      Metric
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        uptrace_tracing_spans
      </code>
    </td>
    
    <td>
      Number of spans and their duration (excluding events and logs)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        uptrace_tracing_events
      </code>
    </td>
    
    <td>
      Number of events (excluding spans and logs)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        uptrace_tracing_logs
      </code>
    </td>
    
    <td>
      Number of logs (excluding spans and events)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        uptrace_service_graph_client_duration
      </code>
    </td>
    
    <td>
      Request duration between two nodes as seen from the client
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        uptrace_service_graph_server_duration
      </code>
    </td>
    
    <td>
      Request duration between two nodes as seen from the server
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        uptrace_service_graph_failed_requests
      </code>
    </td>
    
    <td>
      Total count of failed requests between two nodes
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        uptrace_billing_sampled_bytes
      </code>
    </td>
    
    <td>
      Number of sampled bytes per project
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        uptrace_billing_sampled_spans
      </code>
    </td>
    
    <td>
      Number of sampled spans and logs per project
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        uptrace_billing_dropped_spans
      </code>
    </td>
    
    <td>
      Number of dropped spans and logs per project
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        uptrace_billing_timeseries
      </code>
    </td>
    
    <td>
      Number of active timeseries per project
    </td>
  </tr>
</tbody>
</table>

## Related

- [Dashboard YAML Templates](/features/dashboards/yaml) — full YAML schema reference
- [Querying metrics](/features/metrics/querying) — MQL query language for metrics
- [Observability as Code](/features/observability-as-code) — manage dashboards as version-controlled YAML files
- [MCP Server](/features/mcp) — create and update dashboards from AI assistants