diff --git a/blog-service/2025-06-18-dashboards.md b/blog-service/2025-06-18-dashboards.md new file mode 100644 index 0000000000..9456489aae --- /dev/null +++ b/blog-service/2025-06-18-dashboards.md @@ -0,0 +1,12 @@ +--- +title: Scope-Based Variable (Dashboards) +image: https://help.sumologic.com/img/sumo-square.png +keywords: + - dashboard + - scope-based-variable +hide_table_of_contents: true +--- + +import useBaseUrl from '@docusaurus/useBaseUrl'; + +We’re excited to introduce a new dashboard variable type: Scope-Based Variables. Scope-Based Variables act as log filters that can be automatically applied to all or selected panels within a dashboard. This helps you to easily filter data across multiple panels without needing to manually edit each panel’s query to accept the variable. [Learn more](/docs/dashboards/filter-template-variables). diff --git a/docs/dashboards/filter-template-variables.md b/docs/dashboards/filter-template-variables.md index 4774cb7b56..3eac64a006 100644 --- a/docs/dashboards/filter-template-variables.md +++ b/docs/dashboards/filter-template-variables.md @@ -21,7 +21,8 @@ The web interface autocomplete feature for log search variables has the follow * It is updated every night for the last 24 hours starting from 10PM PT to the previous day at 10PM PT.  * Only dashboards that were viewed in the last 3 days are updated. * Up to 10,000 log values and 1,000 metric values are displayed. -* Values for template variables are based on the time range of the Dashboard. +* Values for template variables (except Scope Based Variable) are based on the time range of the dashboard. +* New panels added to the dashboard will automatically adopt any existing Scope-based Variable to it. ## Show and hide variables option @@ -29,11 +30,12 @@ In the Dashboard top menu bar, click the filter icon to show the variables optio ## Create a template variable -There are three types of template variables you can use as a dashboard filter: +There are four types of template variables you can use as a dashboard filter: * Custom List - a custom set of options * Metrics Metadata Search - metrics metadata based options  * Log Search - logs query based options +* Scope-based Variable - define scope variables to automatically apply to all log queries ### Add a Custom List variable @@ -46,6 +48,7 @@ To add a Custom List variable to a dashboard, do the following: 1. In the **Create Template Variable** panel, enter a unique **Variable Name**. Spaces and special characters, with the exception of an underscore (_), are not allowed in value names.
Create-Template-Variable-dialog 1. Select **Custom List** as the **Variable Type**. 1. **List Items** are your variable values. Use a comma separated list for variable options, separating individual options with a comma. For example, `small, medium, large`. +1. (Optional) **Include the option to select all values (\*)** will be selected by default. This includes a wildcard asterisk (\*) in the available options. 1. (Optional) Provide a **Default Value** for the variable. 1. Click **Create Template Variable** to apply the variable to the dashboard.  @@ -61,6 +64,7 @@ To add a Metrics Metadata Search variable to a dashboard, do the following: 1. Select **Metrics Metadata Search** as the **Variable Type**. 1. The **Fields (key)** is the metadata field you want to use as the filter. 1. (Optional) **Filters** allow you to filter the scope of your data before choosing the field you want to use. Click in the **Filter** input, begin typing, and choose a filter from the pop-up list. A list of valid values appears. Select a value for the filter, and add other filters as needed. +1. (Optional) **Include the option to select all values (\*)** will be selected by default. This includes a wildcard asterisk (\*) in the available options. 1. (Optional) Provide a **Default Value** for the variable. 1. Click **Create Template Variable** to apply the variable to the dashboard. @@ -76,6 +80,29 @@ To add a Logs Search variable to a dashboard, do the following: 1. Select **Logs Search** as the **Variable Type**. 1. Click in the **Query** field and begin typing your query. Select valid options from the pop-up list as they appear until your query is complete. 1. The **Key** is the metadata field you want to use as the filter. Once a Key is selected the Preview table will show example values based on the query running for the last 15 minutes. +1. (Optional) **Include the option to select all values (\*)** will be selected by default. This includes a wildcard asterisk (\*) in the available options. +1. (Optional) Enter a **Default Value** for the variable. +1. Click **Create Template Variable** to apply the variable to the dashboard. + +### Add a Scope-based Variable + +With a Scope-based Variable, you can define a variable that automatically applies to all log queries within the scope of the dashboard or panels. By setting a key while creating the scope variable, you can select values to enable simple filtering for the dashboard. Additionally, you can specify which panels the scope variable applies to for more granular control. + +:::info +- The fields in the Scope-based Variable are independent of dashboard and panel time range. +- Fields in the Scope-based Variable will also contain the FER field keys. +::: + +To add a Scope-based Variable to a dashboard, do the following: + +1. In the Dashboard top menu bar, click the filter icon to show the variables option. The filter icon allows you to toggle if the variables option is displayed or hidden.
Show-and-Hide-filters +1. In the Dashboard top menu bar, click the **plus (+) icon**. The **Create Template Variable** panel appears.
create-dashboard-filter +1. In the **Create Template Variable** panel, enter a unique **Variable Name**. Spaces and special characters, with the exception of an underscore (_), are not allowed in value names.
scope-based-variable +1. Select **Scope-based Variable** as the **Variable Type**. +1. The **Filds (key)** is the metadata field you want to use as the filter. Once a Key is selected the Preview table will show example values based on the query running for the last 15 minutes. +1. (Optional) **Display all values available** will be selected by default. If you want to specify any values, deselect this option and enter the required value(s) in section below. +1. (Optional) **Apply filter to all panels in dashboard** will be selected by default. If you want to apply this variable to secleted panel, deselect this option and select the panels from the dropdown. You can also click on preview-the-panels to preview and select the dashboard panel to which you want to apply this variable. +1. (Optional) **Include the option to select all values (\*)** will be selected by default. This includes a wildcard asterisk (\*) in the available options. 1. (Optional) Enter a **Default Value** for the variable. 1. Click **Create Template Variable** to apply the variable to the dashboard. diff --git a/static/img/dashboards/filter-template-variables/Create-Template-Variable-dialog.png b/static/img/dashboards/filter-template-variables/Create-Template-Variable-dialog.png index 5c9466ee93..ddb2e8fc07 100644 Binary files a/static/img/dashboards/filter-template-variables/Create-Template-Variable-dialog.png and b/static/img/dashboards/filter-template-variables/Create-Template-Variable-dialog.png differ diff --git a/static/img/dashboards/filter-template-variables/Variable-for-logs-search.png b/static/img/dashboards/filter-template-variables/Variable-for-logs-search.png index 4d5532b2ff..6521c3dbdb 100644 Binary files a/static/img/dashboards/filter-template-variables/Variable-for-logs-search.png and b/static/img/dashboards/filter-template-variables/Variable-for-logs-search.png differ diff --git a/static/img/dashboards/filter-template-variables/dashboard-new-metrics-metadata-search-variable.png b/static/img/dashboards/filter-template-variables/dashboard-new-metrics-metadata-search-variable.png index f9d3614039..325d128ed5 100644 Binary files a/static/img/dashboards/filter-template-variables/dashboard-new-metrics-metadata-search-variable.png and b/static/img/dashboards/filter-template-variables/dashboard-new-metrics-metadata-search-variable.png differ diff --git a/static/img/dashboards/filter-template-variables/preview-the-panels.png b/static/img/dashboards/filter-template-variables/preview-the-panels.png new file mode 100644 index 0000000000..2f859c0b0a Binary files /dev/null and b/static/img/dashboards/filter-template-variables/preview-the-panels.png differ diff --git a/static/img/dashboards/filter-template-variables/scope-based-variable.png b/static/img/dashboards/filter-template-variables/scope-based-variable.png new file mode 100644 index 0000000000..fb34c8a0bc Binary files /dev/null and b/static/img/dashboards/filter-template-variables/scope-based-variable.png differ