Filter a dashboard

This document describes how you can add template variables, filters, and groupings to your custom dashboards. Temporary filters and groupings let you modify what the charts on a dashboard display for your current session. Template variables and permanent filters let you create menus whose values you modify to change what the dashboard displays.

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.

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. Permanent filters can apply to some or to all dashboard widgets.

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.

Before you begin

To create or modify permanent filters, ensure that you have one of the following Identity and Access Management roles:

  • roles/monitoring.dashboardEditor
  • roles/monitoring.editor
  • roles/monitoring.admin
  • roles/owner

For more information about roles, see Access control.

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.

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:

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:

  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 ensure its legend is displayed. If the legend isn't shown, then click Toggle 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 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:

  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 ensure its legend is displayed. If the legend isn't shown, then click Toggle 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:

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:

  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 ensure its legend is displayed. If the legend isn't shown, then click Toggle 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:

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

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:

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

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 template variable or 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 dashboard-wide filter:

      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 template variable:

      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.

  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 template variable or 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 template variable or 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

When the dashboard editor is open, you can apply a template variable to a specific widget by doing any of the following:

What's next