> 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/use-groundcover/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](/use-groundcover/dashboards-and-alerts/dashboard-catalog.md) instead.
{% endhint %}
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.
### Create a new Widget
Widgets can be added by clicking on the **Create New Widget** button in case of a new Dashboard or Create Widget at the top right in case there is at least one widget.
### **Choose a Widget Type**
Widgets are the main building blocks of dashboards. groundcover supports the following widget types:
* **Chart Widget**: Visualize your data through various display types.
* **Textual Widget**: Add context to your dashboard, such as headers or instructions for issue investigations.
* **Section Widget**: Group related widgets together
{% hint style="info" %}
Since selecting a Textual or Section Widget is the last step for this type of widget, the rest of this guide is relevant only to Chart Widgets.
{% endhint %}
### **Select a Data Type**
**One Chart Widget is selected, the widget builder will open.**
**The first step is to select the data type to query out of the following:**
| Data type | Use for |
| ------------- | ------------------------------------------ |
| **Metrics** | Metric time series, rates, aggregations |
| **Logs** | Log volume, counts, grouped log tables |
| **Traces** | Trace latency, errors, grouped trace views |
| **Events** | Kubernetes and platform events |
| **Entities** | Infrastructure entity data |
| **Issues** | Issue-oriented signals |
| **RUM** | Real user monitoring data |
| **APM** | Application performance views |
| **Ingestion** | Ingestion and pipeline metrics |
### Build your query
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](/use-groundcover/querying-your-groundcover-data/explore-and-monitors-query-builder.md) for full details on the different components.
{% endhint %}
### **Choose a Visualization Type**
There are six ways to visualize your query, each one with different configuration options.
Refer to the [visualization types](/use-groundcover/dashboards-and-alerts/dashboard-visualizations.md) page to read more about the visualization and configuration options.
## **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**
1. Click on **Add Variable** and configure the variable using the following fields.\
2. The **data source** to be used:
1. `Suggested Variables` - A predefined list of popular variables which use 'All Datasources' behind the scenes.
2. `All Data Sources` - Will show values for the chosen key across all data sources.
3. Specific data types - Only show values for the chosen key for data coming from the selected source.
3. Choose the **label key** to be used to fetch values from the data source selected.
4. Choose the **name** of the variable to be used in the widgets with `$` as explained below.
### **Using a Variable**
Variables can be referenced in the Filter Bar of the Widget Builder Modal using their name.
1. In this following example we selected Clusters from the predefined list, and named it 'clusters'.
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`).
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 widget queries, you may select the values to filter and choose the default to be used when the dashboard loads on first time.
5. 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.
1. For example- selecting the value `production` in a variable called `cluster` which uses the key `cluster` from `All Data Sources.` When going to the `workloads` variable, the 'Associated Values' section will list the `workload` values that are in the `production` cluster.
2. Below in the 'Additional Values' will be shown all other values.
3. The association is done by relevant data types only, if you are getting unexpected associated results you may be advised to narrow down the data sources that the variable uses from 'All Data Sources' to a specific type or a specific metric.
4. 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.
---
# 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 current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.groundcover.com/use-groundcover/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 optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
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.