Add temporary filters to a custom dashboard

This document describes how you can change what data is displayed on a custom dashboard—without having to modify each widget—by adding temporary groupings and temporary filters. After you add a dashboard-wide grouping or filter, the dashboard toolbar displays a menu item for that grouping or filter.

When troubleshooting, you can modify the data a dashboard displays by adding temporary groupings or filters. For example, if you are investigating an incident and want the dashboard to only display data for a specific virtual machine (VM), then add a temporary filter.

Temporary groupings and filters are automatically deleted when you reload the page; however, you can also delete them manually.

For information about how to create permanent filters, see Add permanent filters to custom dashboards.

How dashboard filters work

A dashboard filter specifies a label and a value. The time series that the dashboard displays determine the labels available for filtering. How a widget supports a dashboard-wide filter depends on the type of data the widget displays, and the configuration of the widget:

For widgets that display time-series data, such as a line charts, the following rules apply:
- If the time series displayed by the widget doesn't support the label in a filter, then the dashboard-wide filter doesn't change the displayed data.
  
  For example, if you add a filter on the label instance_id, but a chart on the dashboard doesn't display data with an instance_id label, then the filter doesn't change the displayed data.
- If the widget specifies a value for a label, then the dashboard-wide filter doesn't change the displayed data.
  
  For example, if you add a filter on the label instance_id, but a chart on the dashboard includes a filter based on the instance_id label, then the dashboard-wide filter doesn't change the displayed data.
- Otherwise, the chart filters the data it displays to only those time series that satisfy the dashboard-wide filter.
For logs panel widgets, dashboard-wide filters that are based on a resource label update the query. For example, if you add the dashboard-wide filter cluster_name: mycluster, then the query is updated to include resource.labels."cluster_name"="mycluster".

You can add multiple dashboard-wide filters. These filters are joined with a logical AND.

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.

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

Create or modify temporary groupings

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 create or modify the temporary groupings, do the following:

In the navigation panel of the Google Cloud console, select Monitoring, and then select Dashboards:
Go to Dashboards
Expand the Group By menu and then select the labels for grouping.
Click OK.

When you navigate away from the dashboard, any groupings that you created are discarded.

Create 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 create 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, create a filter based on the label instance_id. Similarly, to configure the dashboard to only show time series for a specific zone, create a filter based on the label zone.

To create a temporary filter, do the following:

In the navigation panel of the Google Cloud console, select Monitoring, and then select Dashboards:
Go to Dashboards
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 zone: *.
To select a specific value to match, click the filter, for example, click zone: *, 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 navigate away from the dashboard, any filters that you created 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:

Display of the Example dashboard.

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:

In the navigation panel of the Google Cloud console, select Monitoring, and then select Dashboards:
Go to Dashboards
Identify the chart and expand the legend to see more details by clicking Expand legend.
Scroll through the legend until you find the specific time series of interest, click Actions for this timeseries, and then 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:

Display of the Example dashboard with filters for all labels of a cpu utilization time series.

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

Display of the Example dashboard with filters for all labels of a disk read bytes time series.

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:

In the navigation panel of the Google Cloud console, select Monitoring, and then select Dashboards:
Go to Dashboards
Identify the chart and expand the legend to see more details by clicking Expand legend.
Scroll through the legend until you find the specific time series of interest, click Actions for this timeseries, and then select Filter dashboard to resource labels.

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:

Display of the Example dashboard with filters for the resource labels of a cpu utilization time series.

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:

In the navigation panel of the Google Cloud console, select Monitoring, and then select Dashboards:
Go to Dashboards
Identify the chart and expand the legend to see more details by clicking Expand legend.
Scroll through the legend until you find the specific time series of interest, click Actions for this timeseries, and then select Filter dashboard to metric labels.

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 navigate away from the dashboard. To manually remove a temporary filter, on that filter, click Delete.