> 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/create-a-dashboard.md). # Creating Dashboards {% hint style="info" %} **Note**: Only users with Write or Admin permissions can create and edit dashboards. {% endhint %} ## **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?** {% hint style="info" %} Don't want to build from scratch? Install a ready-made dashboard from the [Dashboard Catalog](/investigate/dashboards-and-alerts/dashboard-catalog.md) instead. {% endhint %} ### 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, at two levels. 1. **The whole dashboard.** The star button in the dashboard toolbar — **Edit with Agent** — takes an instruction about the dashboard as a whole: add a section for database health, re-scope every widget to a different namespace, drop the widgets nobody reads. The Agent's proposal renders in place, over the dashboard you're looking at, and nothing is written until you act on it: | Action | Effect | | ---------------- | ---------------------------------------------------------------- | | **Save** | Accepts the proposal and saves it as the dashboard's new version | | **Make changes** | Reopens the prompt to refine the proposal further | | **Cancel** | Discards the proposal and returns to the saved dashboard | A run in progress can be stopped, and a follow-up instruction sent while it is still working is picked up by that run. 2. **One widget.** 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. ### Create Manually 1. Navigate to the [**Dashboards**](https://app.groundcover.com/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. {% hint style="info" %} **There is no Save button.** A dashboard saves itself as you work — adding, editing, moving or removing a widget, and changing variables or layout settings, are all persisted automatically a moment after the change. Leaving the page waits for a pending save to land. One thing is deliberately *not* autosaved, because it changes what everyone sees when the dashboard opens: the **default time range**. Set it explicitly with **Actions → Set time as default**. {% endhint %} ### 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. Written in markdown, with a formatting toolbar and a preview tab, and can be given one of the section colors	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 Widget** menu — **Create with AI**, **Widget Builder**, or **Text Widget** — which places the new widget inside that section rather than at the end of the dashboard. {% hint style="info" %} 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. {% endhint %} #### Text widgets A text widget is a markdown note on the dashboard. Click it to edit: the editor has a formatting toolbar and an **Edit** / **Preview** pair of modes, so you can check how a note renders before clicking away. Clicking outside the widget finishes editing. Like a section, a text widget can be painted from the shared color palette — useful for making a runbook step or a warning stand out from the charts around it. ### **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](/investigate/dashboards-and-alerts/dashboard-visualizations.md) 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. {% hint style="info" %} If you're unfamiliar with query building in groundcover, refer to the [Query Builder section](/investigate/querying-your-groundcover-data/explore-and-monitors-query-builder.md) for full details on the different components. {% endhint %}

## **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. ### Opening a widget on its own Expanding a widget — the expand icon in its header, or `F` — opens it large, with a control row of its own above the chart: | Control | Scope | | -------------- | ---------------------------------------------------------------------------- | | **Variables** | The variables this widget's queries actually use, re-selectable here | | **Time range** | A range for this widget alone. Until you pick one it follows the dashboard's | | **Refresh** | Re-runs this widget's queries | Everything in that row is **ad hoc**: it applies to the expanded widget only, is never saved to the dashboard, and leaves the dashboard's own variables and time picker untouched. It's the way to zoom one chart out to a week, or swap it onto another cluster, without disturbing a dashboard the rest of your team is looking at. ### 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 Widget places a new widget inside the section, built by the Agent, in the Widget Builder, or as text
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](#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`). {% hint style="info" %} 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. {% endhint %} 3. 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:.*)`

4. 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](/investigate/saved-views.md) 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](/investigate/dashboards-and-alerts/managing-dashboards-with-terraform.md). ## **Renaming and re-tagging a dashboard** **Actions → Edit Details** reopens the name, description and tags a dashboard was created with. Renaming a dashboard doesn't change its URL, so existing links and sidebar pins keep working. ## **Finding and organizing dashboards** Use [favorites and sidebar pins](/investigate/dashboards-and-alerts.md#find-your-frequently-used-dashboards) to keep the dashboards you use most easy to find. Favorites let you filter the list to your selection; pins give you direct access from the sidebar. Both are personal. 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](/investigate/dashboards-and-alerts/dashboard-version-history.md). --- # 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 dynamically 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/create-a-dashboard.md?ask=&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 `build a script that syncs our docs to a CMS` 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.