Skip to content

Commit 5bda230

Browse files
yubonluokolchfa-aws
yubonluo
and
kolchfa-aws
authored
[Variable] Add documentation for dashboard variables (#12445)
* add dashboard variables documentation Signed-off-by: yubonluo <yubonluo@amazon.com> * fix lint error Signed-off-by: yubonluo <yubonluo@amazon.com> * fix link error Signed-off-by: yubonluo <yubonluo@amazon.com> * Doc review Signed-off-by: Fanit Kolchina <kolchfa@amazon.com> --------- Signed-off-by: yubonluo <yubonluo@amazon.com> Signed-off-by: Fanit Kolchina <kolchfa@amazon.com> Co-authored-by: Fanit Kolchina <kolchfa@amazon.com>
1 parent 6e34479 commit 5bda230

14 files changed

Lines changed: 661 additions & 0 deletions

‎.github/vale/styles/OpenSearch/ImageHTMLTag.yml‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
extends: existence
2+
message: "Use Kramdown image syntax instead of HTML <img> tags. See FORMATTING_GUIDE.md for details."
3+
level: warning
4+
nonword: true
5+
scope: raw
6+
tokens:
7+
- '(?<!\{::nomarkdown\})<img\s+src='

‎_dashboards/dashboard-variables/index.md‎

Lines changed: 161 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,161 @@
1+
---
2+
layout: default
3+
title: Dashboard variables
4+
has_children: true
5+
nav_order: 75
6+
redirect_from:
7+
- /dashboards/dashboard-variables/
8+
---
9+
10+
# Dashboard variables
11+
**Introduced 3.7.0**
12+
{: .label .label-purple }
13+
14+
Using dashboard variables, you can create interactive, dynamic dashboards by defining reusable values that can be referenced in visualization queries. Variables can be used for filters, metrics, dimensions, intervals, fields, aggregations, and any other query parameter, eliminating the need to manually edit queries.
15+
16+
Dashboard variables are available in **Observability** workspaces only. To use dashboard variables, create an Observability workspace if you don't already have one.
17+
{: .note}
18+
19+
Use dashboard variables to:
20+
21+
- Change query parameters without editing visualizations.
22+
- Define values once and reference them across multiple visualizations.
23+
- Automatically update visualizations when variable values change.
24+
- Create cascading filters with dependent variables.
25+
- Dynamically control grouping, aggregation, and time intervals.
26+
27+
## Variable types
28+
29+
OpenSearch Dashboards supports two types of variables:
30+
31+
- **Query variables**: Options are dynamically fetched from a data source using a Piped Processing Language (PPL) or Prometheus Query Language (PromQL) query. Use query variables when values change over time or depend on underlying data, such as service names from logs or available regions from metrics.
32+
33+
- **Custom variables**: Options are manually defined as a static list. Use custom variables for predefined categories like environment types (`dev`, `staging`, `prod`) or fixed status codes.
34+
35+
## Variable syntax
36+
37+
You can reference variables in queries using `$variableName` or `${variableName}` syntax:
38+
39+
```sql
40+
source=logs | where service='${service}' | stats count() by region
41+
```
42+
{% include copy.html %}
43+
44+
When you change a variable's value in a dashboard, all visualizations referencing that variable automatically refresh using the new value.
45+
46+
## Enabling dashboard variables
47+
48+
In your `opensearch_dashboards.yml` file, configure the following settings:
49+
50+
```yaml
51+
workspace.enabled: true
52+
explore.enabled: true
53+
```
54+
{% include copy.html %}
55+
56+
Restart OpenSearch Dashboards for the changes to take effect.
57+
58+
## Creating and using dashboard variables
59+
60+
The following tutorial uses the OpenSearch Dashboards sample web logs dataset to create a variable and use it in a visualization.
61+
62+
### Step 1: Create a workspace
63+
64+
1. Navigate to the OpenSearch Dashboards home page.
65+
1. Select **Create workspace**.
66+
1. Enter a workspace name (for example, `My Observability`).
67+
1. Under **Use case**, select **Observability**.
68+
1. Select **Create workspace**.
69+
70+
For more information, see [Create a workspace]({{site.url}}{{site.baseurl}}/dashboards/workspace/create-workspace/).
71+
72+
### Step 2: Set up sample data
73+
74+
1. In the workspace, navigate to **Manage workspace** > **Sample data** and select **Add data** for the web logs dataset.
75+
1. Create an index pattern for the sample data:
76+
1. Navigate to **Manage workspace** > **Index patterns**.
77+
1. Select **Create index pattern**.
78+
1. In the **Index pattern name** field, enter `opensearch_dashboards_sample_data_logs`.
79+
1. Select **Next step**.
80+
1. In the **Time field** dropdown, select `timestamp`.
81+
1. Select **Create index pattern**.
82+
83+
### Step 3: Create a variable
84+
85+
1. Select **Dashboards** in the left navigation.
86+
1. Select **Create** > **Dashboard**.
87+
1. Save the dashboard by entering a title (for example, `Log Analysis`) and selecting **Save**.
88+
1. At the top of the dashboard, select **Add variable**.
89+
1. Configure the following settings:
90+
- **Name**: `extension`
91+
- **Type**: **Query**
92+
- **Dataset**: Select `opensearch_dashboards_sample_data_logs`
93+
- **Options Query**:
94+
95+
```sql
96+
source=opensearch_dashboards_sample_data_logs | stats count() by extension | fields extension
97+
```
98+
{% include copy.html %}
99+
100+
1. Select **Preview** to verify the results. The preview should display values: `css`, `deb`, `gz`, `rpm`, and `zip`.
101+
1. Select **Add variable** to save.
102+
103+
The `extension` variable now appears at the top of the dashboard with a dropdown.
104+
105+
For more information, see [Managing dashboard variables]({{site.url}}{{site.baseurl}}/dashboards/dashboard-variables/managing-variables/).
106+
107+
### Step 4: Use the variable in a visualization
108+
109+
1. In the dashboard, select **Create new**.
110+
1. Select **Add visualization** to open the visualization editor.
111+
1. In the query editor, enter the following PPL query that references the `$extension` variable:
112+
113+
```sql
114+
| where extension='$extension' | stats count() by response
115+
```
116+
{% include copy.html %}
117+
118+
1. In the `extension` dropdown at the top of the editor, select a value (for example, `css`).
119+
1. Select **Update** to run the query.
120+
121+
The visualization displays the response code distribution filtered by the selected extension, as shown in the following image.
122+
123+
![Visualization editor showing a bar chart of response codes filtered by the selected extension value]({{site.url}}{{site.baseurl}}/images/dashboard-variables/variable-visualization-result.png)
124+
125+
When you change the `extension` value in the dropdown, the visualization automatically updates to reflect the new selection.
126+
127+
If no results appear, expand the time range (for example, **Last 90 days**) using the [time filter]({{site.url}}{{site.baseurl}}/dashboards/discover/time-filter/) in the upper-right corner.
128+
{: .tip}
129+
130+
For more information, see [Using dashboard variables]({{site.url}}{{site.baseurl}}/dashboards/dashboard-variables/using-variables/).
131+
132+
## Variable storage
133+
134+
Variables are stored as part of the dashboard saved object in OpenSearch. Each dashboard maintains its own set of variables independently.
135+
136+
The `variablesJSON` attribute in the dashboard saved object contains the variable configurations:
137+
138+
```typescript
139+
{
140+
type: "dashboard",
141+
id: "dashboard-id",
142+
attributes: {
143+
title: "My Dashboard",
144+
variablesJSON: "{\"variables\":[...]}"
145+
}
146+
}
147+
```
148+
{% include copy.html %}
149+
150+
Variable configurations include the following components:
151+
152+
- Metadata (name, label, description, type).
153+
- Options (query definition for query type or custom values for custom type).
154+
- Settings (multi-select, "All" option, sort order, visibility).
155+
- Current values (selected values for each variable).
156+
157+
Current variable values are also synchronized to the dashboard URL so that you can:
158+
159+
- Share dashboards with specific filter values preselected.
160+
- Bookmark dashboards with desired variable states.
161+
- Persist variable selections across page refreshes.

‎_dashboards/dashboard-variables/managing-variables.md‎

Lines changed: 157 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,157 @@
1+
---
2+
layout: default
3+
title: Managing dashboard variables
4+
parent: Dashboard variables
5+
nav_order: 10
6+
---
7+
8+
# Managing dashboard variables
9+
10+
You can create, edit, delete, organize, and view dashboard variables from within a dashboard.
11+
12+
## Prerequisites
13+
14+
Before you start, ensure that you have met the following prerequisites:
15+
16+
- Dashboard variables are [enabled]({{site.url}}{{site.baseurl}}/dashboards/dashboard-variables/#enabling-dashboard-variables) in your `opensearch_dashboards.yml` file.
17+
- You have an [Observability workspace]({{site.url}}{{site.baseurl}}/dashboards/workspace/create-workspace/) set up.
18+
19+
For the complete setup, see [Creating and using dashboard variables]({{site.url}}{{site.baseurl}}/dashboards/dashboard-variables/#creating-and-using-dashboard-variables).
20+
21+
## Creating a variable
22+
23+
To create a new variable, follow these steps:
24+
25+
1. In your Observability workspace, select **Dashboards** in the left navigation.
26+
1. Open an existing dashboard or select **Create** > **Dashboard** to create a new dashboard. If creating a new dashboard, save it first by entering a title and selecting **Save**.
27+
1. At the top of the dashboard, select **Add variable**.
28+
1. Configure the variable settings. The Add variable panel contains the following sections:
29+
30+
- **General configuration**:
31+
- **Name** (required): The identifier used to reference the variable in queries using `$variableName` or `${variableName}` syntax.
32+
- **Label** (optional): A display name shown at the top of the dashboard.
33+
- **Description** (optional): Additional context about the variable's purpose.
34+
- **Type** (required): Select **Query** or **Custom**. For more information about variable types, see [Variable types]({{site.url}}{{site.baseurl}}/dashboards/dashboard-variables/#variable-types).
35+
- **Query type configuration** (for query type variables):
36+
- **Options Query**: Define a query to fetch variable options dynamically.
37+
- If needed, update the default language (PPL) to PromQL using the language toggle.
38+
- In the **Select dataset** dropdown list, select a dataset. For PPL, select an index pattern. For PromQL, select a Prometheus data source.
39+
- Write a query that returns a single column of values.
40+
- Select **Preview** to validate the query and view the first 100 results.
41+
- **Regex** (optional): Filter query results using a regular expression. Only values matching the pattern are displayed.
42+
- **Refresh**: Choose when to update variable options:
43+
- **On dashboard load**: Options are fetched once when the dashboard loads.
44+
- **On time range change**: Options refresh automatically when the dashboard time range changes.
45+
- **Custom type configuration** (for custom type variables):
46+
- **Custom options**: Enter custom values for the variable. Type a value and press Enter to add it. The maximum of 100 options can be displayed in the dropdown list.
47+
- **Selection configuration** (available for both query and custom types):
48+
- **Sort**: Choose how options are sorted in the dropdown list (**Disabled**, **Alphabetical** (ascending or descending), or **Numerical** (ascending or descending)).
49+
- **Allow multiple selections**: Enables you to select multiple values from the dropdown.
50+
- **Include All option** (only available when multiple selections are enabled): Adds an **All** option to the dropdown that selects all available values.
51+
52+
1. Select **Add variable** to save.
53+
54+
The variable appears at the top of the dashboard.
55+
56+
## Managing existing variables
57+
58+
The **Manage variables** panel lists all existing variables, including their type, name, and configuration options. To access this panel, follow these steps:
59+
60+
1. Navigate to your workspace.
61+
1. From **Dashboards**, select the dashboard to update.
62+
1. On the top, toggle the **Edit** selector to enter edit mode.
63+
1. In the upper-left corner, select the **Manage variables** icon, as shown in the following image.
64+
65+
![Manage variables panel displaying variable names, types, and action icons]({{site.url}}{{site.baseurl}}/images/dashboard-variables/manage_panel.png)
66+
67+
The **Manage variables** icon only appears when variables have been created in the dashboard. If no variables exist, create one first before accessing the management interface.
68+
{: .note}
69+
70+
## Editing a variable
71+
72+
To edit an existing variable, follow these steps:
73+
74+
1. Open the **Manage variables** panel.
75+
1. Select the **Edit** icon for the variable you want to modify.
76+
1. Make your changes.
77+
1. Select **Update variable** to save.
78+
79+
Changing the variable name causes any queries that reference the old name to fail.
80+
{: .note}
81+
82+
## Deleting a variable
83+
84+
To delete a variable, follow these steps:
85+
86+
1. Open the **Manage variables** panel.
87+
1. Select the **Delete** icon for the variable you want to remove.
88+
1. Confirm the deletion in the dialog.
89+
90+
Variables that are referenced by other variables or visualization editors display an indicator in the management panel. Deleting a referenced variable causes any queries that use it to fail.
91+
{: .note}
92+
93+
## Organizing variables
94+
95+
Variables are displayed at the top of the dashboard in the order they appear in the management panel.
96+
97+
To reorder variables, follow these steps:
98+
99+
1. Open the **Manage variables** panel.
100+
1. Drag the reorder handle on the left side of a variable.
101+
1. Drop it in the desired position.
102+
1. Save the dashboard to apply the new order.
103+
104+
## Hiding variables
105+
106+
You can hide variables from the top of the dashboard while keeping them available for use in queries.
107+
108+
To hide or show a variable, follow these steps:
109+
110+
1. Open the **Manage variables** panel.
111+
1. Select the **Hide/Show** icon for the variable.
112+
1. Save the dashboard to apply the change.
113+
114+
Hidden variables are marked with a **Hidden** badge in the management panel and do not appear in the dashboard.
115+
{: .note}
116+
117+
## Variable status indicators
118+
119+
Each variable displays a status indicator at the top of the dashboard:
120+
121+
- **Loading**: A spinner appears while the system fetches options.
122+
- **Error**: An error icon appears with a tooltip showing the error message. The dropdown is disabled.
123+
- **No options**: If a variable query returns no results, "No options" is displayed in the dropdown.
124+
125+
## URL synchronization
126+
127+
Variable values are automatically synchronized to the dashboard URL using the `variableValues` query parameter:
128+
129+
```js
130+
?variableValues=(service:(api),region:(us-east,us-west))
131+
```
132+
133+
URL synchronization enables the following functionality:
134+
135+
- Send a link to a dashboard with specific variable values preselected.
136+
- Save a dashboard view with your preferred variable settings.
137+
- Preserve variable selections across page refreshes.
138+
139+
## Variable dependencies
140+
141+
Query type variables can reference other variables in their queries. The following example shows a query variable that references another variable:
142+
143+
```sql
144+
source=logs | where region=$region | dedup service | fields service
145+
```
146+
{% include copy.html %}
147+
148+
In this example, the `service` variable depends on the `region` variable. When the `region` variable changes, the `service` variable automatically refreshes its options.
149+
150+
Keep the following considerations in mind:
151+
152+
- Avoid circular dependencies where Variable A references Variable B, and Variable B references Variable A.
153+
- Variables are evaluated in the order they appear in the management panel. Place dependent variables after the variables they reference.
154+
155+
## Next steps
156+
157+
- [Using dashboard variables]({{site.url}}{{site.baseurl}}/dashboards/dashboard-variables/using-variables/)

0 commit comments

Comments
 (0)