> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chronosphere.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Customize panel queries with dashboard variables

*Dashboard variables* are uniquely named placeholders that you can use in dashboards
to dynamically replace their values with user-defined values. For instance, you
can add variables to [panels](/observe/dashboards/panels) to let users customize
them across all of a dashboard's panels without editing each panel individually.

<Note>
  If you've used other observability tools, you might have encountered dashboard
  variables by the names *template variables*.
</Note>

After you [create a dashboard variable](#create-a-dashboard-variable), you can add
it to a panel using the syntax `$<NAME>`, where `<NAME>` is the variable's name.
Variables are most often used in [queries](/investigate/querying) but also work
in panel names and descriptions, and also in the content of
[Markdown panels](/observe/dashboards/panels/markdown). Expressions also support variables.

For example, part of a panel's query might match a `service` named `production`:

```text theme={null}
service=~"production"
```

You can create a dashboard variable named `service` and replace the string value
with `$service`:

```text theme={null}
service=~"$service"
```

Dashboard viewers can then change all uses of `$service` in each panel by changing
that dashboard variable in one place, instead of editing each panel manually.

Dashboard variables can accept either user-defined [text values](#configure-a-text-variable)
or offer a [list of values](#configure-a-list-variable), whether manually defined or
dynamically generated from labels or a query, for the user to select.

## Variable suggestions in panel queries

When you edit a panel query on a standard dashboard, Observability Platform can
suggest replacing a literal label value in PromQL with an existing dashboard variable.
Observability Platform can also help you add a `$<NAME>` reference that isn't configured on
the dashboard yet.

Variable suggestions apply only to PromQL on the **Metrics (Prometheus)** datasource,
not in Metrics Explorer. For details, see
[Variable suggestions](/observe/dashboards/panels#variable-suggestions) in the panel
documentation.

## View dashboard variables

Dashboard variables add a dropdown selector to the dashboard's header for each variable.

To view a list of all of a dashboard's variables:

1. Open the dashboard. You can
   [view a list of all dashboards](/observe/dashboards#view-dashboards) or select
   from a [list of dashboards in a collection](/administer/collections/home).
2. On the dashboard, click **Variables** or click
   <Icon icon="settings" alt="Settings icon" />**Settings <span aria-label="and
   then">></span> Variables**.

The **Dashboard variables** panel lists all dashboard variables defined for this
dashboard in a table. Columns indicate each variable's
[visibility](#toggle-dashboard-variable-visibility), name, and type. Each variable
includes controls to [reorder](#define-the-order-of-dashboard-variables),
[edit](#configure-a-dashboard-variable), and [delete](#delete-a-dashboard-variable)
variables. Depending on your Observability Platform configuration, a variable row
can also include **Apply to panels**, which opens a tool to
[add that variable to many panel queries at once](#apply-a-variable-to-multiple-panels).

## Create a dashboard variable

To add a dashboard variable to a dashboard:

1. [View the list of dashboard variables](#view-dashboard-variables).
2. In the **Dashboard variables** panel, click
   **<Icon icon="plus" alt="Add variable icon" /> Add variable**. By default,
   this creates a new [text variable](#configure-a-text-variable).
3. To create a different variable type, make a selection from the **Type** menu.
4. Enter the variable's **Name**, which defines the name used to address the variable
   in a query or text.
5. Enter a **Display label**.
6. Enter a **Description**.
7. Click **Apply**.
8. Click **Save** to save the dashboard and new variable.

After configuring a variable and saving the dashboard, the dashboard updates with
a new group of fields for [saved views](#saved-views).

## Configure a dashboard variable

To configure a dashboard variable:

1. [View the list of dashboard variables](#view-dashboard-variables).
2. In the **Dashboard variables** panel, click
   **<Icon icon="plus" alt="Add variable icon" /> Add variable**. By default,
   this creates a new [text variable](#configure-a-text-variable).
3. On the row of the variable you want to edit, click
   **<Icon icon="pencil" alt="Edit variable icon" /> Edit variable**.
4. After configuring the variable, click **Apply** to confirm the changes.

### Configure a text variable

In a *text variable*, the dashboard user can define the variable's value by entering
it into a text field.

To configure a text variable:

1. [Configure](#configure-a-dashboard-variable) or [create](#create-a-dashboard-variable)
   a dashboard variable.
2. If the variable **Type** isn't **Text**, click **Type**, then click **Text**.
3. Optional: Set a **Display label**, which appears in the variable's field instead of its name.
4. Optional: Set a **Description**.
5. Optional: Enter a **Value** for the template variable.
6. After configuring the variable, click **Apply** to confirm the changes.

### Configure a list variable

In a *list variable*, the dashboard user can define the variable's value by selecting
it from a list.

To configure a list variable:

1. [Configure](#configure-a-dashboard-variable) or [create](#create-a-dashboard-variable)
   a dashboard variable.
2. If the variable **Type** isn't **List**, select **List** from the **Type** dropdown.
3. Select a **Source**:
   * **\[Static] Custom list**: Define the available options by entering them into the
     **Values** field.
   * **\[Prometheus] Label values**: Select a label name and Observability Platform adds the
     values of labels of the matching series to the list. You can filter the values
     by series by using PromQL
     [time series selectors](https://prometheus.io/docs/prometheus/latest/querying/basics/#time-series-selectors).
     If you don't define any series selectors, Observability Platform defaults to using all
     series. To select from multiple series, click **Add series selector**. Each series
     selector row has a **Code** / **Builder** toggle. Use **Code** mode to type the
     selector as a PromQL expression directly. Use **Builder** mode to construct the
     selector using form fields, without writing PromQL.
   * **\[Prometheus] Label names**: Observability Platform adds all label names to the
     list. You can also filter these names by series using PromQL time series
     selectors.
   * **\[Prometheus] PromQL result values**: Enter a PromQL query and Observability
     Platform adds values from the result to the list. You can also filter the
     results by label name.
   * **\[Logs] Logs field values**: Enter the log field name you want to define a
     variable for.
4. Optional: Filter the results further by entering a
   [**Regex**](/investigate/querying/regular-expressions) filter, which
   includes only the results that match the expression.
5. Optional: Set the variable's **Refresh** toggle to define whether Observability
   Platform updates its list values **On dashboard load** or **On time range change**.
6. Optional: To allow the user to select multiple values from the list, enable
   **Select multiple values**.
7. Optional: To add an option to select all values from the list, enable **Include "All" option**.
   You can also define the regular expression representing all values by setting
   the **Custom "All" value**.
8. To confirm and apply the new variable configuration, click **Apply**.
9. Optional: To cancel any changes to the variable, click **Cancel**.

As you configure the variable, Chronosphere reflects any changes you make to the
list variable and reports any errors in the **Preview values** list. You can also
**<Icon icon="rotate-cw" alt="Refresh icon" /> Refresh** the preview to update
its values and **<Icon icon="clipboard" alt="Copy icon" /> Copy** the
list of previewed values as a comma-separated list.

### Configure an interval variable

Use an *interval* variable to set a default time period for a dashboard.

1. [Configure](#configure-a-dashboard-variable) or
   [create](#create-a-dashboard-variable) a dashboard variable.
2. Set the **Type** to **Interval**.
3. In the **Interval options** text box, add a time period. This should be a
   numerical time amount, followed by a time unit. The following are examples of usable time periods:
   * `30s`
   * `5m`
   * `6h`
   * `1d`
4. Toggle **Include "Auto" option** to set a minimum interval when auto is enabled.
5. Click **Add**.
6. Click **Apply**.

After you configure the variable, your dashboard displays the interval as a dropdown
list before your panels.

## Apply a variable to multiple panels

<Note>
  This feature isn't available to all Chronosphere Observability Platform users and
  might not be visible in your app. For information about enabling this feature in your
  environment, contact [Chronosphere Support](/support).
</Note>

When [viewing dashboard variables](#view-dashboard-variables) while the dashboard
is in edit mode, you can add a variable into supported queries on several panels in
one step instead of editing each panel separately.

To apply a variable to multiple panels:

1. Open the dashboard in edit mode.

2. Open the **Dashboard variables** panel by clicking **Variables** or
   <Icon icon="settings" alt="Settings icon" />**Settings <span aria-label="and
   then">></span> Variables**.

3. On the row for the variable you want to use, click **Apply to panels**.

   A drawer opens titled **Manage variable: `$<NAME>`**, where *`<NAME>`* is the
   variable's name.

4. Do one of the following based on the variable **Type**:
   * For an **Interval** variable: Observability Platform injects the variable into
     range vector durations in supported queries. For example, a literal like
     `[5m]` can become `[$<TIME>]`.
   * For other variable types: In **Label name**, select or type the Prometheus
     label to match. The user interface adds a label matcher that uses the variable, in the form
     `label=~"$<NAME>"`, with your chosen label instead of `$<NAME>`.

5. In the panel list, select each panel where you want the variable injected.

   **Select all** and **Select none** apply only to panels that support injection
   and don't already use the variable. Panels that already reference the variable,
   or that use query types that don't support injection, display without a checkbox.
   You can also click a row to toggle its checkbox.

6. Click **Apply** in the drawer.

   If some panels fail to update, an error message lists those panels. When at least
   one panel updates successfully, you can undo the change from the confirmation
   that appears.

7. Click **Save** on the dashboard to persist changes to the dashboard and its
   panels.

## Delete a dashboard variable

To delete a dashboard variable:

1. [View the list of dashboard variables](#view-dashboard-variables).
2. On the row of the variable you want to edit, click
   **<Icon icon="trash" alt="Delete variable icon" /> Delete variable**.

   This action immediately deletes the variable without confirmation. Ensure that you
   want to delete the variable before clicking the icon.
3. To apply the variable deletion and other changes to dashboard variables, click
   **Apply**.
4. Optional: To cancel any deletions and other changes to dashboard variables, click
   **Cancel**.

## Define the order of dashboard variables

Dashboards present dashboard variables from left to right in the same order as
they appear in the **[Dashboard Variables](#view-dashboard-variables)** list.

To reorder dashboard variables:

1. [View the list of dashboard variables](#view-dashboard-variables).
2. On the row of the variable you want to reorder, click
   **<Icon icon="arrow-up" alt="Reorder up icon" /> Reorder variable up** or
   **<Icon icon="arrow-down" alt="Reorder down icon" /> Reorder variable down**
   to move the variable within the list to the position you want.
3. To confirm and apply the new variable order and other changes to dashboard variables,
   click **Apply**.
4. Optional: To cancel any changes to dashboard variables, click **Cancel**.

## Toggle dashboard variable visibility

You can define whether a dashboard variable appears on its dashboard. This helps
you create and test dashboard variables without disrupting other users, and helps
users curate large lists of dashboard variables to focus on what they want to analyze.

## Advanced variable syntax

Observability Platform supports the following advanced variables:

* `regex`: Format multivalued variables into a regular expression string.
* `pipe`: Format multivalued variables into a pipe-separated (`|`) string.
* `percentencode`: Encode variables for use in URL parameters.
* `raw`: Don't apply formatting to the variable, use as-is.

The Observability Platform variable substitution logic is designed for PromQL,
as PromQL queries need escaped values because they're inside string literals. To
opt out of using escaped values, add `:raw` as a suffix to your variable.

For example, `${varexample:raw}:` can be used like `"${api_endpoint:raw}"`.

## Saved views

Saved views let you use defined dashboard variables to change the dashboard view with
different settings, while using the same panels.

If you have saved custom dashboard variables, the **Saved View** menu displays. The menu
is a list of all the views available for this dashboard. Select a view from the
**Saved View** menu to display a different view. The currently selected view has a
<Icon iconType="solid" icon="check" color="#60E684" /> green checkmark next to the
name. Saved views are sorted alphabetically with the **Default view** at the top,
so your selected view might not be at the top of the list.

Each available variable displays after the view name, in the order
[they're defined](/observe/dashboards/customization/dashboard-variables#define-the-order-of-dashboard-variables).
[Pinned scope](/navigate/pinned-scopes) values override variable values in saved views.

If you hold the pointer over an item in the **Saved View** menu, the view settings
display. The list includes the view's time period and the variable names and values
saved for the selected view.

If you change a variable value, the name in your **Saved view** includes a `changed`
indicator.

### Update the view

You can save multiple views for a dashboard. To save a view if you add a value to a
variable's text:

1. Click the **Saved View** menu.
2. Choose **Create new view** to save a new view, or **Update view** to overwrite
   the current view's values. A confirmation message with the new values displays.
3. If you select **Create new view**, add a **Name** and then click **Save**.
4. If you select **Update view**, decide if you want to **Save current time range a
   default**, and then click **Save**.

To change the view name or set a new default view:

1. Open the **Saved View menu**.
2. Hold the pointer over the view you want to edit.
3. Click **<Icon icon="pencil" /> Edit**.
4. Optional: Update the **Name**.
5. Optional: Select **Save as default view** to set this view as the **Default view**.
6. Click **Save**.

### Delete a view

You can't delete the **Default View**. To delete a custom saved view:

1. Open the **Saved View menu**.
2. Hold the pointer over the view you want to delete.
3. Click **<Icon icon="trash" /> Delete**.