# Creating dashboards

{% hint style="info" %}
**Note**: Only users with Write or Admin permissions can create and edit dashboards.
{% endhint %}

## **How to create a new Dashboard in groundcover?**

1. Navigate to the **Dashboard List** and click on the **Create New Dashboard** button.
2. Provide an indicative name for your dashboard and, optionally, a description.

<figure><img src="/files/R4dgY7YAXjT5NCZBzlJQ" alt=""><figcaption></figcaption></figure>

#### **Steps to creating a Dashboard**

1. Create a new widget
2. Choose a Widget Type
3. Select a Widget Mode
4. Build your query
5. Choose a Display Type
6. Save the widget

Optional:

1. Add variables
2. Apply variable(s) to the widget

### Create a new Widget

Widgets can be added by clicking on the **Create New Widget** button.

### **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.

{% hint style="info" %}
Since selecting a Textual Widget is the last step for this type of widget, the rest of this guide is relevant only to Chart Widgets.
{% endhint %}

### **Select a Widget Mode**

* **Metrics**: Work with all your available metrics for advanced use cases and custom metrics.
* **Infra Metrics**: Use expert-built, predefined queries for common infrastructure scenarios. Ideal for quick starts.
* **Logs**: Query and visualize log data.
* **Traces**: Query and visualize trace data similar to logs.

### Build your query

Once the Widget Mode selected, build your query for the visualization.

{% 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 %}

<figure><img src="/files/tu4xuqJ9N7RIKGu4yZGm" alt=""><figcaption></figcaption></figure>

### **Choose a Display Type**

<table><thead><tr><th width="173">Type</th><th>Configuration options</th><th>Supported modes</th></tr></thead><tbody><tr><td><strong>Time Series</strong></td><td><p>Choose a Y-axis unit from the predefined list.</p><p>Select a visualization type: Stacked Bar or Line Chart.</p></td><td><p>Metrics</p><p>Infra Metrics</p><p>Logs</p><p>Traces</p></td></tr><tr><td><strong>Table</strong></td><td><p>Define columns based on data fields or metrics.</p><p>Choose a Y-axis unit from the predefined list.</p></td><td><p>Metrics</p><p>Infra Metrics</p><p>Logs</p><p>Traces</p></td></tr><tr><td><strong>Stat</strong></td><td>Select a Y-axis unit from the predefined list.</td><td><p>Metrics</p><p>Infra Metrics</p><p>Logs</p><p>Traces</p></td></tr><tr><td><strong>Top List</strong></td><td>Choose a ranking metric and sort order.</td><td><p>Logs</p><p>Traces</p></td></tr><tr><td><strong>Pie</strong></td><td>Select a data source and aggregation method.</td><td><p>Logs</p><p>Traces</p></td></tr></tbody></table>

## **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.

Our predefined variables cover most use cases, but if you’re missing an important one, let us know. Advanced variables are also on our roadmap.

### **Adding a Variable**

1. Click on **Add Variable** and configure the variable using the following fields.![](/files/KlKzlyuDMACVKo5QGN63)
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 Datsources` - Will show values for the chosen key from logs, traces, *all* metrics, and events.
   3. `Traces`, `Logs`, `Events` - Only show values for the chosen key for data coming from these sources.
   4. `Metrics` - Show values for a chosen label key from a chosen metric name.![](/files/bDl14Xmt0srlYVUUbplj)
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 Creation 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 filter 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:.*)`

<figure><img src="/files/SW1EBmGYzyNrYzXzWXRt" alt=""><figcaption></figcaption></figure>

4. After configuring the Variable in the widget queries, you may select the values you which 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 Datasources`, then when going to `workloads` variable I can see in the 'Associated Values' section a list of `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 Datasources' 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.

<figure><img src="/files/sl2DYJ4MQ4cBiHKQymUD" alt=""><figcaption></figcaption></figure>


---

# Agent Instructions: 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:

```
GET https://docs.groundcover.com/use-groundcover/dashboards-and-alerts/create-a-dashboard.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.