Filter a custom dashboard

This document describes how you can add template variables, filters, and groupings to your custom dashboards. To create a filter that lasts only for your current session, add a temporary filter. You can also create permanent filters. Permanent filters can apply to the entire dashboard or, when you specify a template variable, only to select dashboard widgets. Lastly, to aggregate time series for all widgets on a dashboard, add a temporary grouping.

When a custom dashboard is in read-only mode, the dashboard-level filters and groupings are displayed, along with menus. You can use these menus to change the current value of the filter; however, the changes you make apply only to your current session.

The instructions in this document are for the Google Cloud console. For information about how to add template variables and permanent filters to custom dashboards by using the Cloud Monitoring API, see Dashboard filters.

How dashboard filters work

Dashboard filters compare a label to a value. The labels in the time series your dashboard displays determine the labels available for filtering. For example, you can filter by the label instance_id when a dashboard displays data for a VM instance.

A dashboard filter applies to a chart only when the chart supports the filter label and when the chart doesn't specify a value for that label. For example, when a chart includes the filter zone = us-central1-a, that chart ignores a dashboard filter based on the label zone. Similarly, charts without a zone label ignore dashboard filters with this label.

When you add multiple filters, the widgets show only those time series that satisfy all filters.

Best practices

To temporarily modify what data a dashboard displays, add temporary filters or temporary groupings. For example, when you are investigating an incident and want the dashboard to only display data for a specific virtual machine (VM), add a temporary filter.

To define a default presentation of data on a dashboard along with menu-driven options to modify that display, add permanent filters. For example, when you want to view metrics for all zones and also want to view metrics for a specific zone, create a permanent filter based on the zone label. There are two types of permanent filters:

• A filter that applies to all dashboard widgets is a Dashboard filter.
• A filter that applies to some dashboard widgets is a Template variable.

Before you begin

• To get the permissions that you need to add or modify temporary filters by using the Google Cloud console, ask your administrator to grant you the Monitoring Viewer (roles/monitoring.viewer) IAM role on your project. For more information about granting roles, see Manage access.

  You might also be able to get the required permissions through custom roles or other predefined roles.

• To get the permissions that you need to add or modify permanent filters by using the Google Cloud console, ask your administrator to grant you the Monitoring Editor (roles/monitoring.editor) IAM role on your project. For more information about granting roles, see Manage access.

  You might also be able to get the required permissions through custom roles or other predefined roles.

For more information about roles, see Control access with Identity and Access Management.

Add a temporary filter

When you are investigating an incident, you might want to look at data in specific ways. For example, you might want to view only time series for a specific virtual machine or for resources in a specific region. When you add a temporary filter, all dashboard widgets are modified to show data that matches that filter. For example, to configure all charts to show only time series for a specific VM instance, add a filter based on the label instance_id. Similarly, to configure the dashboard to only show time series for a specific zone, add a filter based on the label zone.

To add a temporary filter, do the following:

1. In the Google Cloud console, select Monitoring or click the following button:
   Go to Monitoring
2. In the navigation pane, select Dashboards, then select the dashboard that you want to view or edit.
3. If the Close editor button is shown, then click it.

4. In the dashboard's filter bar, click Add filter, and then select a label from the menu. The menu lists the labels for every time series shown on the dashboard.

   After you select a label, a filter is added to the dashboard toolbar. The filter's name has the same name as your selection, and its value is set to *, which matches all values. For example, if you select zone, then the toolbar displays a filter with the name of zone.

5. To select a specific value to match, in the filter, click Menu, and then select a value from the menu. To reduce the number of menu options, enter part of the value into the Filter area.

When you open the dashboard editor or navigate away from the dashboard, any filters that you added are discarded.

Add temporary filters that match a time series

When you want more information about a specific time series shown on a chart, you can use the chart's legend to apply temporary filters. You can apply filters that match the specific labels of the time series, that match the resource of the time series, or that match just the metric's labels. This section describes those options.

Example dashboard

To help describe the behavior of the different options, consider a dashboard that displays the CPU utilization and Disk read bytes metrics for Compute Engine VM instances. The following screenshot shows this dashboard for one system:

Filter by all labels of a time series

When you want to apply the most restrictive set of labels, filter by all labels. With this option, the labels identify a unique resource and a unique set of values for the labels of the metric.

To apply temporary filters that identify a specific time series on a chart, do the following:

1. In the Google Cloud console, select Monitoring or click the following button:
   Go to Monitoring
2. In the navigation pane, select Dashboards, then select the dashboard that you want to view or edit.
3. If the Close editor button is shown, then click it.
4. Identify the chart and expand the legend to see more details by clicking Expand legend.

5. Add the temporary filters:

   1. Scroll through the legend until you find the specific time series of interest.
   2. Click Actions for this timeseries.
   3. Select Filter dashboard to all labels.

For example, when these steps are applied to the chart that displays the CPU utilization metric for the Example dashboard, the following filters are added:

• Metric label: instance_name.

• Resource labels for Compute Engine VM instances:

  • project_id
  • instance_id
  • zone

The following screenshot illustrates the result:

In the previous figure, the chart displaying the CPU utilization metric shows a single time series. This behavior is because you added filters that match the time series labels. However, the chart that displays the Disk read bytes metric is showing multiple time series. The Disk read bytes metric contains three labels in addition to the label instance_name, so it's possible for multiple time series on this chart to refer to the same instance.

As a comparison, when the previous steps are applied to the chart that displays the Disk read bytes metric for the Example dashboard, the following filters are added:

• Metric labels:

  • instance_name
  • device_name
  • storage_type
  • device_type

• Resource labels for Compute Engine VM instances:

  • project_id
  • instance_id
  • zone

As shown in the previous screenshot, both charts now display a single time series.

Filter by resource labels of a time series

When you filter by all resource labels, you restrict the dashboard to show time series for a specific resource. You can now view the metrics for just that resource, temporarily eliminating from the display those time series that aren't of interest.

To apply temporary filters that identify the resource for a specific time series displayed by a chart, do the following:

1. In the Google Cloud console, select Monitoring or click the following button:
   Go to Monitoring
2. In the navigation pane, select Dashboards, then select the dashboard that you want to view or edit.
3. If the Close editor button is shown, then click it.
4. Identify the chart and expand the legend to see more details by clicking Expand legend.

5. Add the temporary filters:

   1. Scroll through the legend until you find the specific time series of interest.
   2. Click More options.
   3. Select Filter dashboard to resource labels.

   When you group time series, this option might not be available.

For example, when these steps are performed on the chart that displays the CPU utilization metric for the Example dashboard, then three filters are added. These filters correspond to the labels for the resource, a VM instance:

As illustrated in the previous screenshot, when you filter by resource, a chart might display multiple time series.

Because the option Filter dashboard to resource labels applies only resource labels to the temporary filter bar, the result is the same when you select this option from either chart.

Filter by metric labels of a time series

This option lets you apply filters that match the values for the labels of a metric. For example, when you are viewing load-balancing metrics, you might want to view time series that are only for a specific protocol.

To apply temporary filters that identify the metric for a specific time series displayed by a chart, do the following:

1. In the Google Cloud console, select Monitoring or click the following button:
   Go to Monitoring
2. In the navigation pane, select Dashboards, then select the dashboard that you want to view or edit.
3. If the Close editor button is shown, then click it.
4. Identify the chart and expand the legend to see more details by clicking Expand legend.

5. Add the temporary filters:

   1. Scroll through the legend until you find the specific time series of interest.
   2. Click More options.
   3. Select Filter dashboard to metric labels.

   When you group time series, this option might not be available.

For example, when these steps are performed on the chart that displays the CPU utilization metric for the Example dashboard, then a filter based on the label instance_name is added. In this case, it's possible that both charts display multiple time series because the value of the instance_name label is configurable. That is, you can have multiple VMs with the same value for the instance_name label.

As a comparison, when the previous steps are applied to the chart that displays the Disk read bytes metric for the Example dashboard, then four filters are added. These filters correspond to the labels for the Disk read bytes metric.

When your temporary filters include only metric filters, then you see time series for that metric, regardless of the resource against which the time series was written. Because you aren't restricting the time series to a specific resource, you might see multiple time series on a chart. The previous screenshot illustrates this behavior, as both charts display two time series.

Modify or delete a temporary filter

Temporary filters are deleted automatically when you open the dashboard editor or navigate away from the dashboard.

To modify or remove a temporary filter when you are viewing a dashboard and the Edit dashboard button is shown, do the following:

1. Click Menu on the filter that you want to modify or remove.
2. Select an option from the menu. To remove the filter, scroll to the end of the list and click Remove filter.

Create a permanent filter

When you design a dashboard, you might identify multiple ways to view the data the dashboard displays. For example, when a dashboard displays metrics for VM instances, you might want to view metrics for all VMs and you might want to view metrics for VMs in a specific zone. You could create a permanent dashboard-wide filter for the zone label with the default set to all zones, *. When viewing the dashboard, you can use the menu on the zone filter to select a specific zone.

To restrict a permanent filter to specific widgets, create a template variable. Consider a scenario where you want a side-by-side view of metrics for VMs in two different zones. You construct two collections of charts and create a template variable for each collection. Your default configuration satisfies your original objective. However, when viewing the dashboard, the toolbar lists your variables and includes menus to let you select different values. You can use these menus to view data for different zones.

To create a permanent filter, do the following:

1. In the Google Cloud console, select Monitoring or click the following button:
   Go to Monitoring
2. In the navigation pane, select Dashboards, then select the dashboard that you want to view or edit.
3. If the Edit dashboard button is shown, then click it.
4. If there isn't a list of filters shown at the top of the dashboard, click Edit dashboard filters in the dashboard toolbar.

5. Do one of the following:

   • To add a filter that applies to all widgets on the dashboard, do the following:

     1. Adjacent to the text Dashboard filters, click Add.
     2. Select a label from the Label menu.
     3. Select a value from the Default value menu. To match all values, choose *.

   • To add a filter that applies to some widgets on the dashboard, do the following:

     1. Adjacent to the text Template variables, click Add.

     2. Enter a name for the variable in the Template variable text box.

        The name that you enter is shown on the dashboard when the editor is closed. It also is shown in Template variable field of a widget's configuration pane.

     3. Select a label from the Label menu.

     4. Select a value from the Default value menu. To match all values, choose *.

     5. Expand the Apply to charts menu and select the charts that the filter applies to.

        Note: If a widget is configured by using Monitoring Query Language or PromQL, then you can't select that widget in the Apply to charts menu. However, you can configure these widgets to use template variables by editing the JSON definition of the dashboard. For more information, see Apply a template variable to a widget.

6. Optional: To hide the list of dashboard filters, click Edit dashboard filters.

7. Click Close editor.

   The dashboard toolbar displays the new permanent filter. For dashboard-wide filters, the filter name matches the label name. For template variables, the filter name matches the variable name.

8. Optional: To temporarily change the value of the filter, make a selection from its menu.

Modify a permanent filter

When a dashboard isn't editable, permanent filters are shown in the dashboard toolbar. To temporarily change the value of a filter, use its menu.

To change the configuration of a permanent filter, do the following:

1. In the Google Cloud console, select Monitoring or click the following button:
   Go to Monitoring
2. In the navigation pane, select Dashboards, then select the dashboard that you want to view or edit.
3. If the Edit dashboard button is shown, then click it.
4. If there isn't a list of filters shown at the top of the dashboard, click Edit dashboard filters in the dashboard toolbar.
5. Find the filter that you want to modify and then use the menus to make your modifications.
6. Optional: To hide the list of dashboard filters, click Edit dashboard filters.
7. Click Close editor.

Delete a permanent filter

1. In the Google Cloud console, select Monitoring or click the following button:
   Go to Monitoring
2. In the navigation pane, select Dashboards, then select the dashboard that you want to view or edit.
3. If the Edit dashboard button is shown, then click it.
4. If there isn't a list of filters shown at the top of the dashboard, click Edit dashboard filters in the dashboard toolbar.
5. Find the filter that you want to remove and then click Delete.
6. Optional: To hide the list of dashboard filters, click Edit dashboard filters.
7. Click Close editor.

Apply a template variable to a widget

To apply a template variable to a widget that is configured by using Monitoring Query Language or PromQL, do the following:

1. Select the widget to activate the configuration pane.
2. Modify the query string for the widget to include the template variable. For syntax information, see Create and manage dashboards by API: Dashboard filters.

To apply a template variable to a widget that is configured by using the Basic or Advanced tabs, do any of the following:

• Modify the Apply to charts field of the permanent filter. For more information, see Modify a permanent filter.

• Use the Template Variables menu in the configuration pane of the widget. For more information, see Add charts and tables to a dashboard.

For examples of how to add template variables to a widget when you are using the Cloud Monitoring API, see Create and manage dashboards by API: Dashboard filters

Add or modify a temporary grouping

When you add dashboard-wide groupings, the widgets on the dashboard display one time series for each set of time series that have the same values for the grouping labels. By default, the average of each set is shown. However, when the widget defines a grouping function, then that function is used.

For example, assume your dashboard contains a chart that displays the CPU utilization of your VM instances. To determine whether you need to deploy more VMs to a particular zone, you could edit the dashboard and that chart to change its grouping options. An alternative is to temporarily group the dashboard by zone, and then view the CPU utilization chart.

To add or modify the temporary groupings, do the following:

1. In the Google Cloud console, select Monitoring or click the following button:
   Go to Monitoring
2. In the navigation pane, select Dashboards, then select the dashboard that you want to view or edit.
3. If the Close editor button is shown, then click it.
4. Expand the Group By menu and then select the labels for grouping.
5. Click OK.

When you open the dashboard editor or navigate away from the dashboard, any groupings that you added are discarded.

What's next

• Explore charted data
• Access resource-specific dashboards