> For the complete documentation index, see [llms.txt](https://docs.groundcover.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.groundcover.com/investigate/dashboards-and-alerts/dashboard-visualizations.md).

# Dashboard Visualizations

This page documents the **visualization types** available in dashboard widgets and the **configuration options** for each one.

For the overall dashboard workflow (creating widgets, variables, saving, and permissions), see [Creating Dashboards](/investigate/dashboards-and-alerts/create-a-dashboard.md).

To define widgets as JSON, for example in a Terraform `preset`, see the [Dashboard schema](/investigate/dashboards-and-alerts/dashboard-schema.md), which lists the `visualizationConfig` fields for each type.

### Visualization types at a glance

| Visualization   | Best for                                           |
| --------------- | -------------------------------------------------- |
| **Time series** | Trends and rates over time                         |
| **Table**       | Grouped or row-level tabular results               |
| **Stat**        | One or more KPI numbers                            |
| **Top list**    | Ranked values as horizontal bars                   |
| **Pie**         | Share of total across a small number of categories |
| **Treemap**     | Hierarchical share of total across many categories |
| **Data**        | Raw log, trace, or event rows (list-style)         |

In the Widget Builder, switch visualization type using the top left selection. The preview updates immediately; configuration panels below the type change accordingly.

<figure><img src="https://2771001740-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUHgqKYgCiRKdOpWQdi52%2Fuploads%2F23SsFhJ2j1d3kSWadhCT%2Fimage.png?alt=media&amp;token=a756353d-bbeb-4a06-a83f-48fe387e4459" alt=""><figcaption></figcaption></figure>

### Which visualizations each data type supports

Not every data type supports every visualization.

<table data-header-hidden data-search="false"><thead><tr><th width="132.078125"></th><th width="98.63671875"></th><th width="83.734375"></th><th width="69.59765625"></th><th width="100.24609375"></th><th width="67.9140625"></th><th width="94.34765625"></th><th width="85.85546875"></th></tr></thead><tbody><tr><td>Data type</td><td>Time series</td><td>Table</td><td>Stat</td><td>Top list</td><td>Pie</td><td>Treemap</td><td>Data</td></tr><tr><td><strong>Metrics</strong></td><td>✓</td><td>✓</td><td>✓</td><td>✓</td><td>✓</td><td>✓</td><td>—</td></tr><tr><td><strong>Logs</strong></td><td>✓</td><td>✓</td><td>✓</td><td>✓</td><td>✓</td><td>✓</td><td>✓</td></tr><tr><td><strong>Traces</strong></td><td>✓</td><td>✓</td><td>✓</td><td>✓</td><td>✓</td><td>✓</td><td>✓</td></tr><tr><td><strong>Events</strong></td><td>✓</td><td>✓</td><td>✓</td><td>✓</td><td>✓</td><td>✓</td><td>✓</td></tr><tr><td><strong>Entities</strong></td><td>—</td><td>✓</td><td>✓</td><td>✓</td><td>✓</td><td>✓</td><td>—</td></tr><tr><td><strong>Issues</strong></td><td>✓</td><td>✓</td><td>✓</td><td>✓</td><td>✓</td><td>✓</td><td>—</td></tr><tr><td><strong>RUM</strong></td><td>✓</td><td>✓</td><td>✓</td><td>✓</td><td>✓</td><td>✓</td><td>—</td></tr><tr><td><strong>APM</strong></td><td>✓</td><td>✓</td><td>✓</td><td>✓</td><td>✓</td><td>✓</td><td>—</td></tr><tr><td><strong>Ingestion</strong></td><td>✓</td><td>✓</td><td>✓</td><td>✓</td><td>✓</td><td>✓</td><td>—</td></tr><tr><td><strong>Cloud Costs</strong></td><td>✓</td><td>✓</td><td>✓</td><td>✓</td><td>✓</td><td>✓</td><td>—</td></tr></tbody></table>

Two exclusions are worth explaining:

* **Entities** has no time series. Entity data describes infrastructure objects as they are now, not as a series over time.
* **Data** is available on Logs, Traces and Events **in Builder mode only**. Switching such a query to the raw editor makes the Data visualization unavailable.

### Multiple queries in one widget

Some visualizations let you add **query B, C, …** or a **formula** query in the same widget.

| Visualization | Multiple queries | Formula |
| ------------- | ---------------- | ------- |
| Time series   | ✓                | ✓       |
| Table         | ✓                | ✓       |
| Stat          | ✓                | ✓       |
| Top list      | ✓                | ✓       |
| Pie           | ✓                | ✓       |
| Treemap       | ✓                | ✓       |
| Data          | —                | —       |

When a widget has more than one query (or a formula), results are shown in a **combined view.** For example, multiple series on one chart or merged table columns.

**Data** widgets always use a single query.

A widget holds at most **10 queries**, and at most **one formula**. Add Query is disabled once you reach ten; Add Formula is disabled once a formula exists.

#### Mixing data sources in one widget

Each query in a widget carries **its own data source**, selected from the data-source control on the query row. One widget can therefore plot a metric alongside a log-derived count, or a trace aggregate beside an APM measurement, as long as every query can draw the widget's visualization type.

A **formula** is the exception: it has no data source control of its own, because it has no data source. A formula computes over the queries it references, so it follows them — including when one of them is switched to a different source.

#### Naming and hiding queries

<table><thead><tr><th width="137.6953125">Control</th><th>Effect</th></tr></thead><tbody><tr><td><strong>Alias</strong></td><td>Renames the query in the legend and in the combined view, instead of showing the raw expression</td></tr><tr><td><strong>Hide query</strong></td><td>Keeps the query in the widget but leaves it out of the rendered result — how you keep a query a formula references without also plotting it. Hide query is only suppored in Data Explore.</td></tr></tbody></table>

Formulas let you combine queries with arithmetic (for example `(A / B) * 100` for a ratio). See [Formulas](/investigate/querying-your-groundcover-data/explore-and-monitors-query-builder.md#formulas) in the Query Builder guide for supported operators and examples.

### Comparing to a previous period

Metrics and APM queries support a **time offset**, which shifts a query back by a fixed duration (for example `1d`, `1w`) without changing the dashboard's time range. Add an offset to a query to overlay it against its own past — for example, plotting today's request rate next to the same metric from exactly one week ago on the same chart.

Each query in a widget can have its own offset, so you can compare more than one prior period at a time.

***

### Cross-cutting configuration options

These settings apply across several visualization types.

#### Rollup interval (bucket size)

For time-bucketed queries, the **rollup interval** controls how data is grouped in time (for example `1m`, `5m`, `1h`). It appears on the query row when the data type supports it.

The effective interval may be **adjusted automatically** to respect a minimum bucket size. Three data types set one, and the clamp is silent — you may see an interval you didn't pick:

<table><thead><tr><th width="164.31640625">Data type</th><th width="175.86328125">Minimum bucket</th></tr></thead><tbody><tr><td><strong>APM</strong></td><td>30 seconds</td></tr><tr><td><strong>Ingestion</strong></td><td>10 minutes</td></tr><tr><td><strong>Cloud Costs</strong></td><td>1 day</td></tr></tbody></table>

#### Data unit

Numeric formatting lives in one panel in the widget builder, which is named for what the visualization actually has:

| Visualization   | Panel                | What it holds                                                                                      |
| --------------- | -------------------- | -------------------------------------------------------------------------------------------------- |
| **Time series** | **Y-Axes**           | A unit **per axis** — see [Y-axis controls](#y-axis-controls). There is no single widget-wide unit |
| Everything else | **Value Formatting** | One **Data Unit** for the widget's values, plus **Precision** on a stat                            |

Whichever panel applies, the unit drives every rendering of the value: labels, axis ticks, legend stats and stat tiles. The units themselves are the same in both:

<table><thead><tr><th width="185.92578125">Unit category</th><th>Examples</th></tr></thead><tbody><tr><td>General</td><td>Number, Percentage, Raw</td></tr><tr><td>Time</td><td>Nanoseconds through Minutes</td></tr><tr><td>Data size</td><td>Bytes, Bytes/sec, KB/s</td></tr><tr><td>Other</td><td>mCPU, Dollars, Req/s</td></tr><tr><td>Custom</td><td>Type a free-text label, for a value none of the built-in units describe</td></tr></tbody></table>

For **tables** with multiple numeric columns, a separate **Data unit overrides** panel sets a **unit per column**, overriding the widget's Data Unit for that column alone. Only stats columns can be given a unit.

#### High series count warning

Time series, table, top list, and pie widgets may return many series or groups. When the result count exceeds the default display limit (**1,000** series), a warning appears above the preview.

| Control          | Behavior                                               |
| ---------------- | ------------------------------------------------------ |
| **Show all**     | Renders more series (up to a hard cap of **5,000**)    |
| Performance note | Showing all series can slow rendering on dense queries |

**Stat** widgets do not offer this toggle; they display up to **50** stat tiles and truncate beyond that.

***

### Time series

**Use when:** You need to see how a metric or aggregated signal changes over the dashboard time range.

#### Chart display type

Under **Additional Styling → Display**:

<table><thead><tr><th width="208.1484375">Option</th><th>Appearance</th></tr></thead><tbody><tr><td><strong>Line</strong></td><td>Separate line per series (default for most data types)</td></tr><tr><td><strong>Bar</strong></td><td>Time buckets as stacked bars</td></tr><tr><td><strong>Area</strong></td><td>Stacked area chart</td></tr></tbody></table>

#### Missing buckets

When a time bucket has no data point, you can choose how gaps are rendered:

| Option              | Effect                                    |
| ------------------- | ----------------------------------------- |
| **Nulls** (default) | Breaks the line / leaves the bucket empty |
| **Zeros**           | Treats missing buckets as zero            |

#### Color palette

Under **Additional Styling → Color**:

| Palette                                         | Description                                       |
| ----------------------------------------------- | ------------------------------------------------- |
| **Classic**                                     | Default product palette                           |
| **Smart**                                       | Semantic coloring (status-aware where applicable) |
| **Red / Green / Blue / Orange / Gray / Purple** | Fixed theme palettes                              |

Color applies across series in the chart (eight-color rotation for time series).

#### Legend

Under **Legend → Mode**:

| Mode        | Behavior                                  |
| ----------- | ----------------------------------------- |
| **Compact** | Inline legend chips below the chart       |
| **Table**   | Tabular legend with optional stat columns |
| **None**    | Legend hidden                             |

When **Table** mode is selected, choose which stat columns appear:

| Column    | Shows                               |
| --------- | ----------------------------------- |
| **Avg**   | Average over the visible time range |
| **Min**   | Minimum value                       |
| **Max**   | Maximum value                       |
| **Sum**   | Sum over the range                  |
| **Value** | Latest / instant value              |

#### Y-axis controls

The **Y-Axes** panel holds one group per axis the chart is drawing. **Left Axis** is always present; **Right Axis** appears only once a query has been moved onto it.

| Setting                 | Description                                                            |
| ----------------------- | ---------------------------------------------------------------------- |
| **Unit**                | The axis' data unit — each axis is formatted independently             |
| **Scale**               | **Linear** (default) or **Logarithmic**                                |
| **Min**                 | Fixed lower bound (leave empty for auto)                               |
| **Max**                 | Fixed upper bound (leave empty for auto)                               |
| **Always Include Zero** | Forces the axis to include zero when compatible with min/max and scale |
| **Show label**          | Shows or hides the axis label                                          |

**Log scale** cannot include zero. If min is above zero or max is below zero, **Always Include Zero** is disabled.

#### Plotting against a second Y-axis

Series in wildly different ranges — a request rate in the thousands and an error percentage under 5 — flatten each other on a single axis. Move one of them to the right axis instead:

1. On the query you want to move, open its **Advanced settings**.
2. Set its **Y-axis** to **Right**.

A **Right Axis** group then appears in the Y-Axes panel, with its own unit, scale and bounds. Each axis is scaled from the queries plotted against it alone, so pinning one side's bounds leaves the other untouched.

Axis assignment is per query, so a widget can put several queries on each side. Moving the last query off the right axis hides the Right Axis group again.

#### Thresholds

Add reference lines or bands to mark meaningful values on the chart — for example an error rate ceiling or an SLO target.

A threshold is either a **line** at a single value or a **range** band between two:

<table><thead><tr><th width="132.4296875">Setting</th><th width="105.13671875">Applies to</th><th>Description</th></tr></thead><tbody><tr><td><strong>Value</strong></td><td>Line</td><td>Where the threshold line/band is drawn on the Y-axis</td></tr><tr><td><strong>Min/ Max</strong></td><td>Range</td><td>The bounds of the band. Leave one empty for a one-sided band</td></tr><tr><td><strong>Label</strong></td><td>Both</td><td>Optional text shown next to the threshold</td></tr><tr><td><strong>Severity</strong></td><td>Both</td><td><strong>Error</strong>, <strong>Warning</strong>, <strong>OK</strong>, or <strong>Info</strong> — controls color</td></tr><tr><td><strong>Style</strong></td><td>Both</td><td><strong>Solid</strong> or <strong>Dashed</strong> line</td></tr></tbody></table>

Each threshold also has its own **visibility** toggle, so you can switch one off without deleting it, and a separate toggle for whether its label is shown.

Add up to **10 thresholds** per widget from the **Thresholds** tab in the widget builder.

#### Interaction on the dashboard

* **Zoom** on the time axis refines the dashboard time range (when chart zoom is enabled on the dashboard view).
* **Hover** over a series will show the value at a specific point along with indication for the step size.

### Table

**Use when:** You need sortable columns, grouped aggregates, or row-level detail in a grid.

#### Configuration in the widget builder

| Option               | Where                     | Description                                          |
| -------------------- | ------------------------- | ---------------------------------------------------- |
| **Data unit**        | Value Formatting panel    | Default formatting for numeric value columns         |
| **Per-column units** | Data unit overrides panel | Available when multiple numeric columns are detected |
| **Rollup interval**  | Query row                 | For time-bucketed SQL/metrics table queries          |

#### Combined tables

When multiple queries feed one table widget, columns from each query are **merged** into a single grid. Per-column units can be set for numeric columns from each query.

#### Conditional formatting

Tables take conditional formatting rules the same way stats do, with one addition: each rule names the **column** it applies to.

| Setting      | Description                                                                            |
| ------------ | -------------------------------------------------------------------------------------- |
| **Apply to** | The column the rule colors. Columns are listed by their current display name           |
| **Rule**     | A comparison and value (or range) to match against                                     |
| **Color**    | **green**, **yellow** or **red**, applied either to the **text** or the **background** |

Rules are evaluated in order and the first match wins. A rule targets a column by identity (its query and field), not by name, so renaming a column keeps its rule attached.

#### Exporting table data

Use **Export** in the widget menu to download the widget's current rows as a CSV file. Available on **Table** and **Data** widgets.

#### Interaction on the dashboard

Hovering over a specific line will show the option to drill down further either in Explore, for aggregated drill down, or to the relevant data type page (e.g. Logs), to see the actual rows.

### Stat

**Use when:** You want a large numeric KPI - one number per series or group.

#### Configuration

<table><thead><tr><th width="189.50390625">Option</th><th>Description</th></tr></thead><tbody><tr><td><strong>Data unit</strong></td><td>Controls value unit of measurement</td></tr><tr><td><strong>Decimals</strong></td><td>Fraction digits shown on the value, from 0 to 4. Defaults to 2</td></tr><tr><td><strong>Rollup interval</strong></td><td>For time-aggregated stats</td></tr></tbody></table>

#### Behavior

* Each series or group renders as a **stat tile** in a responsive grid.
* Up to **50** stats are shown; additional series are truncated.
* With **multiple queries** or a formula, stats from all queries appear in the combined stat grid.

#### Conditional formatting

Color a stat tile based on its value instead of using a single fixed color. Define one or more rules, each with a comparison (`>`, `≥`, `<`, `≤`, `=`, or a range) and a color; the first matching rule wins.

<table><thead><tr><th width="195.94921875">Setting</th><th>Description</th></tr></thead><tbody><tr><td><strong>Rule</strong></td><td>A comparison and value (or range) to match against</td></tr><tr><td><strong>Color</strong></td><td>One of six values: <strong>green</strong>, <strong>yellow</strong> or <strong>red</strong>, each applied either to the <strong>text</strong> or to the <strong>background</strong></td></tr></tbody></table>

Add up to **10 rules** per widget from the **Conditional Formatting** tab in the widget builder.

### Top list

**Use when:** You want a ranked horizontal bar chart (for example “top 10 namespaces by log volume”).

#### Configuration

<table><thead><tr><th width="170.44921875">Option</th><th width="209.9765625">Where</th><th>Description</th></tr></thead><tbody><tr><td><strong>Data unit</strong></td><td>Value Formatting panel</td><td>Value axis formatting</td></tr><tr><td><strong>Color</strong></td><td>Additional Styling</td><td>Single-bar palette (one color theme for all bars)</td></tr><tr><td><strong>Rollup interval</strong></td><td>Query row</td><td>When the query is time-bucketed</td></tr></tbody></table>

#### Behavior

* Bars are ranked by the query’s sort/limit.
* Works with **multiple queries** in combined view (each query contributes bars).
* Supports the high-series warning and **Show all** toggle (same limits as time series).

### Pie

**Use when:** You want proportional breakdowns across a **small** number of categories.

#### Configuration

| Option              | Where                  | Description                                       |
| ------------------- | ---------------------- | ------------------------------------------------- |
| **Data unit**       | Value Formatting panel | Slice value formatting                            |
| **Color**           | Additional Styling     | Multi-slice palette (same options as time series) |
| **Rollup interval** | Query row              | When applicable                                   |

#### Behavior

* Best suited to a limited number of slices (use query **limit** to keep the chart readable).
* Supports **multiple queries** in combined view.
* Supports the high-series warning and **Show all** toggle.

#### Treemap

**Use when:** You want a share-of-total breakdown across **many** categories, where a pie would become unreadable.

A treemap renders the instant result of its queries as rectangles sized by value. Where a pie flattens everything into one ring, additional group-by dimensions become **nested parent groups**, so a treemap can show two levels of breakdown at once — for example namespaces containing workloads.

**Configuration**

<table><thead><tr><th width="144.29296875">Option</th><th width="186.10546875">Where</th><th>Description</th></tr></thead><tbody><tr><td><strong>Data unit</strong></td><td>Value Formatting panel</td><td>Value formatting</td></tr><tr><td><strong>Color</strong></td><td>Additional Styling</td><td><strong>Classic</strong> or <strong>Smart</strong> only — the fixed theme palettes don't apply</td></tr></tbody></table>

**Behavior**

* Available for every data type.
* At most **20 rectangles** are drawn side by side at any one level. Beyond that, the smallest are rolled up into a single **Other** rectangle carrying their combined value.

**Combined view**

A treemap with more than one query doesn't merge their results into one ranking — that would compare values that may not share a unit or a meaning. Instead each query becomes **its own top-level rectangle**, labelled with that query's alias, and that query's group-by breakdown nests inside it. Sizing within an area reflects that query alone.

A single-query treemap has no such wrapper: its group-by breakdown sits at the top level, as before. A query that errors or returns no rows is left out without restructuring the areas around it.

A formula behaves like any other query here, occupying its own area.

### Data

**Use when:** You want a **scrollable list of raw records -** similar to the Logs, Traces, or Events explorers - embedded in a dashboard tile.

#### Availability

| Requirement | Detail                                              |
| ----------- | --------------------------------------------------- |
| Data types  | **Logs**, **Traces**, or **Events** only            |
| Query mode  | **Builder** mode only (not the raw SQL/editor mode) |
| Query count | **Single query** per widget                         |

#### Configuration

| Option               | Description                                                 |
| -------------------- | ----------------------------------------------------------- |
| **Column selectors** | Choose which fields appear (builder query row)              |
| **Filters**          | Standard gcQL / filter builder for the signal type          |
| **Limit**            | Controls page size; scroll or load more for additional rows |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.groundcover.com/investigate/dashboards-and-alerts/dashboard-visualizations.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.