Dashboard-wide filters

This document describes how to configure all widgets on a dashboard to group time series or to restrict which time series the widget displays. Dashboard-wide filtering is useful when, for example, you are investigating the behavior of a specific resource and you don't want to view time series written against different resources.

You can apply groupings by using the Group By button in the dashboard toolbar. You can apply dashboard-wide filters by using the filter bar, or by using options included with a table legend.

General behavior

All dashboard-wide 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 virtual machine (VM) instance. When a chart doesn't support a label specified by a dashboard-wide filter, that filter doesn't change what the chart displays. For example, a filter based on the label zone only changes charts whose time series include the label zone.

You can add and remove dashboard-wide filters. However, when you navigate away from the current dashboard, any filters that you've applied are discarded.

When you add multiple dashboard-wide filters, the dashboard shows only those time series that satisfy all filters.

Add a grouping

When you add a dashboard-wide grouping, all widgets on the dashboard combine time series by the grouping label. For example, to determine if you need to deploy more VMs to a particular zone, you could view the utilization of your VMs averaged by zone.

To group time series by a label value, do the following:

  1. In the 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 Viewing isn't shown, then click Editing and select Switch to Viewing mode.
  4. In the dashboard's filter bar, click Group By, and then select a label.

You can apply multiple groupings. The time series with the same values for all labels are combined when you group by multiple labels.

To remove a grouping, click Close on the grouping label.

Add a filter

When you are investigating an incident, you might want to view time series for a specific virtual machine or for resources in a specific region. Filters let you view only that data that is of interest to you.

To restrict which time series the dashboard displays, add one or more filters. To add a filter, do the following:

  1. In the 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 Viewing isn't shown, then click Editing and select Switch to Viewing mode.
  4. In the dashboard's filter bar, click the text Filter, and then select a label from the menu of labels.

    The menu includes the labels for every time series shown on the dashboard. When a chart doesn't support a label specified by a dashboard-wide filter, that filter doesn't change what the chart displays.

    To find a specific label, enter part of the label name into the text box. For example, to modify the menu to only display labels that include the letter z, enter z in the text box.

  5. Select the value you want the label to match from the menu.

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.

Add 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 dashboard-wide 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 the dashboard-wide filters that identify a specific time series on a chart, do the following:

  1. In the 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 Viewing isn't shown, then click Editing and select Switch to Viewing mode.
  4. Identify the chart and ensure its legend is displayed. If the legend isn't shown, then click Toggle Legend.
  5. Add the dashboard-wide 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 any time series that aren't of interest.

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

  1. In the 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 Viewing isn't shown, then click Editing and select Switch to Viewing mode.
  4. Identify the chart and ensure its legend is displayed. If the legend isn't shown, then click Toggle Legend.
  5. Add the dashboard-wide 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 dashboard-wide 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 the dashboard-wide filters that identify the metric for a specific time series displayed by a chart, do the following:

  1. In the 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 Viewing isn't shown, then click Editing and select Switch to Viewing mode.
  4. Identify the chart and ensure its legend is displayed. If the legend isn't shown, then click Toggle Legend.
  5. Add the dashboard-wide 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 dashboard-wide 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.

What's next