Creating Dashboards

Note: Only users with Write or Admin permissions can create and edit dashboards.

Overview

Dashboards let you build persistent, shareable views over your observability data. Use them for on-call runbooks, service health boards, incident investigation layouts, and any view you want to revisit without rebuilding queries in Explore.

How to create a new dashboard in groundcover?

Don't want to build from scratch? Install a ready-made dashboard from the Dashboard Catalog instead.

Create with the Agent

The Agent is embedded in the dashboard creation flow. From the Dashboards page, click Create Dashboard and describe the dashboard's goal, including relevant context with @mentions. You can also paste, drag, or attach an image of a dashboard sketch and ask the Agent to turn it into a dashboard. Review the generated layout and widgets, then prompt the Agent again to refine them before saving.

You can also use the Agent from an existing dashboard. Open Create widget and describe the visualization you need, or open any chart widget in the Widget Builder and prompt the Agent to edit its query, visualization, filters, or presentation. Generated changes appear as a preview for you to accept or continue refining.

1. Navigate to the Dashboards page. This page shows all dashboards for the selected backend.

2. Click on the Create Dashboard button.

3. Provide a meaningful name for your dashboard and, optionally, a description.

An empty dashboard layout will appear.

Follow up the steps below to populate your dashboard with widgets.

Create a new Widget

Widgets are the main building blocks of dashboards, and there are three kinds:

Widget type	What it's for	How to add it
Chart	Visualize your data through various display types	The Create widget button
Text	Add context to your dashboard, such as headers or instructions for investigations	Text Widget in the chevron menu
Section	Group related widgets together. See Sections	Section in the chevron menu

The Create widget button goes straight to the widget builder — it is the common case, so it isn't behind a menu. The chevron beside it holds the other two.

A section has its own Add Chart Widget and Add Text Widget actions, which place the new widget inside that section rather than at the end of the dashboard.

A Text or Section widget is finished as soon as you add it, so the rest of this guide is relevant only to Chart Widgets.

Configure the Widget Builder

Once Chart Widget is selected, the widget builder will open.

Customizing the widget with the Agent

The easiest way to configure the widget is by providing guidance to the Agent at the top text box. Write in text or record a message describinig what the widget should present, and all the parameters will be changed accordingly.

Choose a Visualization Type

The first step is to select the visualization type. There are seven ways to visualize your query, each one with different configuration options.

Refer to the visualization types page to read more about the different visualizations and configuration options.

Build your queries

Build one or more queries and formulas to be visualized. Queries can be built using a visual Builder or by providing a MetricsQL/gcQL query.

If you're unfamiliar with query building in groundcover, refer to the Query Builder section for full details on the different components.

Working with chart widgets

Sharing a widget

Every widget and section has a Copy link action (widget menu) that generates a URL pointing directly to that widget. Opening the link scrolls to and highlights the widget automatically — useful for sharing one specific chart in Slack or a ticket instead of the whole dashboard.

Describing a widget

Edit Description in the widget menu attaches a description to a widget, written in markdown. An info indicator then appears on the widget header, and hovering it shows the description — the place to explain what a chart means to whoever reads it at 3am. The first 1,000 characters are displayed.

Sections take a description the same way.

Opening a widget's data

Two ways to get from a widget to the underlying records:

• Open in Logs / Traces / … in the widget menu opens the widget's query on its own data source page.

• On a table widget, hovering a row offers a drill down — either into Explore for an aggregated view, or into the relevant data type page to see the actual rows.

Keyboard shortcuts

While hovering over a widget, with no text field focused, the following shortcuts apply:

Key	Action	Available when
E	Edit	The dashboard is editable
V	Open the widget for viewing	The dashboard is read-only
F	Fullscreen	Always
D	Duplicate	The dashboard is editable
R	Remove	The dashboard is editable

Sections

A section groups related widgets under a heading — the way to keep a long dashboard navigable. Beyond grouping, a section can be:

Action	Effect
Collapsed	Folds the section away, so a long dashboard can be scanned by heading
Renamed	Changes the heading in place
Colored	Applies one of eight colors, each in a light and a dark variant
Described	Adds a markdown description, shown the same way as a widget's
Duplicated	Copies the section and everything in it
Added to directly	Add Chart Widget / Add Text Widget place a new widget inside the section
Linked to	Copy link produces a URL that opens the dashboard at that section

Layout

Snap to top, also in the Actions menu, pulls widgets upward to close vertical gaps left by resizing or removing a widget.

Drag a widget's corner to resize it, or drag its header to reposition it, in either mode.

Synced crosshair

Toggle Sync Crosshairs from the dashboard's Actions menu to move the hover crosshair across all time-series widgets on the dashboard together, making it easier to compare the same point in time across multiple charts.

Time range

A dashboard opens on whichever time range it was last given, but you can pin one:

• Actions → Set time as default makes the current time range the one the dashboard opens with.

• Actions → Clear default removes it again.

A default time range covers only the time range. To pin variable selections as well, save a view — see Saved views below.

Variables

Variables dynamically filter your entire dashboard or specific widgets with just one click. They consist of a key-value pair that you define once and reuse across multiple widgets.

Adding a Variable

Click Add Variable. The first step is choosing where the variable's values come from:

Kind	Values come from
Dynamic	An existing data source — the values are fetched from your data
Static	A list you author yourself

Dynamic variables

1. Choose the label key to be used to fetch values from the data source selected.

2. Choose the name of the variable to be used in the widgets with $ as explained below.

Key overrides. The same concept is often stored under different keys in different data sources. Rather than creating one variable per source, add a key override for a data source: the variable keeps one name, and resolves to the key you specify when it is used against that source.

Static variables

A static variable owns its options, so it has no data source to fetch them from — you author the list, up to 100 values.

A static variable also has a key separate from its name. The key is the real field your data uses; the name is what you type in a query. That lets a long telemetry key be referenced by something short:

Field	Example
Key	k8s.namespace.name
Name	ns
Values	prod, staging, dev

Referencing $ns in a widget then filters on k8s.namespace.name.

Using a Variable

A variable can be referenced in two forms, which do different things:

Form	Expands to	Use it when
$name	A whole filter atom — the key, the operator and the selected values	You want the variable to filter the query, which is the common case
$name.value	Just the selected value or values, as text	You need the value somewhere a filter atom can't go

$name.value works in positions the bare form deliberately skips: inside a quoted value, for example resource:"…/$feature.value/*".

Referencing a variable in the filter bar

Variables can be referenced in the Filter Bar of the Widget Builder using their name.

1. In this following example a variable called clusters was created.

2. While creating or editing a Chart Widget, add a reference to the variable using a dollar sign in the filter bar, (for example, $clusters).

Each variable has an option of Apply to Widgets. Use it to select specific or all widgets and have the variables added to all their queries automatically.

1. The data will automatically filtered by the variable's key with the selected values. If all values are selected, the filter will be followed by an asterisk (for example, cluster:.*)

1. After configuring the Variable in the queries, you may select the values to filter and choose the default to be used when the dashboard loads on first time.

Variable values selection

After selecting values in at least one Variable, all other relevant Variables will render an 'Associated Values' section in the dropdown list. This list renders the values of the selected variable's key which are associated with the values of the currently selected variables' keys.

In the below example, the value groundcover-backend was selected in the clusters variable. opening the namespaces variable shows 2 types of list of values:

1. The 'Associated Values' section will list the namespaces values that are in the production cluster.

2. All other values will be shown in the 'Additional Values'.

1. Limitations and tips-

   1. It's possible that there are associated values which don't appear in the list, this list is not hermetic, but anything associated is necessarily associated.

   2. Start to type the value you are searching to narrow down the list.

   3. It's possible that Additional Values will also relate to the chosen values of other variables.

Adding a chart from elsewhere

You don't always have to build a widget from scratch inside a dashboard. A chart built while querying data in Explore, or a chart generated inline by the AI assistant, can be saved directly into an existing dashboard via its Add to Dashboard action — pick the target dashboard and the chart is added as a new widget with its query intact.

Saved views

A dashboard has its own saved views, scoped to that dashboard rather than to a page. A view captures the variable selections and the time range, so a dashboard you use several ways — one cluster during an incident, another for a weekly review — can be reopened in each of them without re-selecting anything.

Views appear in the Views selector beside the time picker, and behave like saved views elsewhere in the product. See Saved Views for how views are created, shared, favorited and managed.

You can mark one view as your default. Opening the dashboard then applies it automatically — unless the URL you followed already carries its own variable or time-range state, which always wins, so a shared link still opens on what the sender saw.

Editing the dashboard JSON

Actions → Edit JSON opens the dashboard's underlying definition for direct editing. It is the quickest way to make a change the builder has no control for — renaming a label across every widget, for example.

{% hint style="warning" %} Editing JSON bypasses the widget builder's validation. Prefer the builder for anything it can express, and consider exporting a copy first. {% endhint %}

Exporting and importing

Actions → Export produces the dashboard as JSON or as a Terraform resource. The JSON can be brought back in from the Dashboards list via Import, which is the fastest way to copy a dashboard between backends. For the Terraform path, see Managing Dashboards with Terraform.

Finding and organizing dashboards

The Dashboards list supports:

• Tags — apply free-form labels to a dashboard and filter the list by tag.

• Search — filter by name, tag, owner, or description.

• Archive / Restore — archive a dashboard to hide it from the default list without permanently deleting it, and restore it later. Archived dashboards can still be permanently deleted if no longer needed.

• Saved views — the Dashboards list itself supports saved views, capturing the active status tab and sort.

Keeping dashboards in sync

If someone else saves changes to a dashboard while you're viewing it, groundcover shows a notice that a newer version is available. Refresh to pick up their changes before making your own edits, so you don't unknowingly overwrite them.

If you do need to recover from an overwritten or unwanted change, see Dashboard Version History.