Configuring a Target Metric

This page describes how to use the metric-selection tool to specify a target metric for an alerting policy. The chart next to the Target region gives you visual feedback on the data being captured by the target.

The Target region uses the same metric selector that is used in Metrics Explorer and for creating charts. If you are already familiar with it, you can skip this page.

Selecting a metric

To select a metric, use the Find resource type and metric field to choose one resource type and one metric type. You can specify them in either order. To begin, click in the field. This brings up one or two lists, based on any prior selections. The lists are indicated by headers, Resource types and Metrics, as seen in the following screenshot:

Search lists for selecting metrics and resources.

You can select an entry in two ways:

  • By selecting entries from the lists.

  • By entering a metric filter. To enter a metric filter, do the following:

    1. Next to Find resource type and metric, click Help
    2. Click Direct filter mode in the help pane.

      When Direct filter mode is enabled, the Find resource type and metric option is replaced with an editable text box labeled Resource type, metric, and filter:

      Direct filter mode is displayed.

      If you made selections for a resource type, a metric, or a filter prior to selecting Direct filter mode, then those settings are used to prepopulate the Resource type, metric, and filter text box.

    3. Enter a metric filter in the Resource type, metric, and filter text box. Your filter must include a metric type and a resource type. You can also include label filters. For the filter grammar, see Monitoring filters.

      For example, to display the log entries for all Google Cloud VM instances in the us-east1-b zone, enter the following:

      metric.type="" resource.type="gce_instance" resource.label."zone"="us-east1-b"

      If you've used direct filter mode to configure charts or alerting policies and no data is available, then the chart displays an error message. The exact error message depends on the filter you entered. For example, a typical message is Chart definition invalid. You might also see the message No data is available for the selected time frame.

Hovering over an item on either list brings up a tooltip that displays the information in the item's descriptor. For information on descriptors for metric types or monitored resources, see the metrics list or the monitored resource list.

When at least one resource type and metric pair is selected, the chart shows all the available time series, and additional items appear below the specified metric on the Metric tab. The following screenshot shows the Metric tab after a metric has been specified:

Display additional selection options.


You can reduce the amount of data returned for a metric by specifying filter criteria, so that only time series that meet some set of criteria are used. If you apply filters, there are fewer lines on the chart, and that can improve the performance of the chart.

You can supply multiple filtering criteria. The corresponding chart shows only the time series that meet all of the criteria, a logical AND.

In the Google Cloud Console, to add a filter, click the Filter field. This opens a panel containing lists of criteria by which you can filter. For example, you can filter by resource group, by name, by resource label, by zone, and by metric label.

The following screenshot shows the known filter-by labels for a project:

Lists of pre-populated filter labels

You can select from the lists or type to find matches. Additionally, you can create filters for data that has not yet appeared; such filter criteria won't appear on the selection list, but you can manually specify filters that you know will be valid in the future.

After you choose a label on which to filter, you have to specify the rest of the filter: a value or range of values and a comparison.

For example, the following screenshot shows a filter on the zone resource label. The Filter field supports a pair of comparison operators for equality, = and =~, and a pair for inequality, != and !=~. The second item in each pair takes a regular-expression as a value. Simple equality, =, is the default.

Filter comparators

Below the list of comparison operators is a list of the available values. The following screenshot shows the names of zones in the project:

Some pre-populated filter values

For the Value field, you can select one of the items on the drop-down list, or you can enter an expression that matches multiple items:

  • If you use a direct comparison, = or !=, you can create a filter string like starts_with. For example, the filter string starts_with("us-central") matches any us-central zone:

    Using a filter string

    See Monitoring filters for more information on filter strings.

  • If you select =~ or !=~ you can use an RE2 regular expression in the value. For example, the regular expression us-central1-.* matches any us-central1 zones:

    Filtering with regexps

    The regular expression ^us.*.a$ matches any US zone that ends with “a”:

    Filtering with more regexps

You can specify multiple filter criteria, and you can use the same label multiple times. This lets you specify a filter for a range of values. To add additional filters, click Add a filter near the bottom of the filter field. Currently, all of the filter criteria must be met; they constitute a logical AND. For example, you can use both starts_with and ends_with filter strings to show only “a” zones in the US:

Using multiple filters


You can reduce the amount of data returned for a metric by combining different time series. To combine multiple time series, you typically specify a grouping and a function. Grouping is done on the basis of labels. The function, called the Aggregator in the Google Cloud Console, is used to combine the time series in the group into a single time series. Typical aggregators include the mean, maximum, minimum, standard deviation, and assorted percentile values.

To add a grouping, click Add a label in the Group by text box, and then make a selection from the menu. The menu is constructed dynamically and displays the available labels. These are the same labels that you can use for filtering. When you add the first grouping option, the following occurs:

  • An aggregator is selected. The selected function is determined by the type of data being displayed; however, you can change this function.
  • The aggregator combines all time series that have the same label value into a single time series.
  • The chart displays one time series for each value of the group-by label.

The following screenshot shows a grouping by user_labels.version with the Aggregator set to the default value of sum:

Example of grouping setting.

This selection results in one time series for each value of the user_labels.version. The data points in each time series are computed from the sum of all the values for individual time series for a specific version:

Showing time series' grouped by user_labels.version

You can group by multiple labels. When you have multiple grouping options, then time series are grouped by each combination of label values, and the aggregator is applied to each group. The resulting chart displays one time series for each combination of label values. The order in which you specify the labels doesn't matter.

For example, the following screenshot illustrates grouping by user_labels.version and system_labels.machine_image:

Showing time series' grouped by version and machine image.

As illustrated, if you group by both the labels, you get one time series for each pair of values. The fact that you get a time series for each combination of labels means that this technique can easily create more data than you can usefully put on a single chart.

If you don't specify a grouping option and do specify an aggregator, then the aggregator is applied to all of the selected time series and results in a single time series. This behavior is illustrated in the following screenshot:

Showing time series' aggregated by sum but no grouping

When you specify grouping or if you select an aggregator, the resulting time series only contains those labels that are mandatory, such as the project identifier, and the labels specified by the grouping.

To remove a group-by condition, you must:

  1. Delete the group-by labels.
  2. Set the aggregator to none.


The Aggregator option lets you combine time series by using common functions. This results in fewer lines on the chart displaying the metric, which can improve the performance of the chart.

Click in the Aggregator field to see a list of the available aggregation options. These are the functions, or reducers, that can be used to combine the time series.

The available reducing functions depend on the type of values the metric captures, but they commonly include choices like mean, max or min, standard deviation, assorted percentile values, and so forth. For more information about these dependencies, see Metrics, time series, and resources.

When used without grouping, the reducing function is applied across all the selected time series, combining them to a single time series consisting of the mean, sum, or other measure as calculated across all the time series. When used with grouping, the function is applied to the time series within each group.

For more information on aggregation, see Aggregation in the API reference.

The Group By option automatically applies aggregation to compute statistics within each group. The lines on a Group By chart already represent aggregations. Group By chooses a default aggregation function based on the type of data being grouped, but you can change this selection.

You can also apply aggregation to a set of time series that you have filtered. As with the unfiltered time series, aggregation of filtered time series will reduce all of the lines to one that reflects the chosen aggregation function, unless you also use grouping.

There are additional options for selecting a metric. These options have default values, but you can expose these options and override the defaults. To see the additional options, click Show advanced options.


A time series is a set of data points in temporal order. To align a time series is to break the data points into regular buckets of time, the alignment period. Multiple time series must be aligned before they can be combined.

Alignment is a prerequisite to aggregation across time series, and it is applied to each time series individually. Because alignment is a prerequisite for charting the data, Monitoring does it automatically, by using default values. You can override these defaults by using the alignment options, Aligner and Alignment Period:

Alignment-option fields

Alignment Period: The alignment period determines the length of time for subdividing the time series. For example, you can break a time series into one-minute chunks or one-hour chunks. The data in each period is summarized so that a single value represents that period. The default alignment period is one minute.

Although you can set the alignment interval for your data, time series might be realigned when you change the time interval displayed on a chart or change the zoom level.

Aligner: The aligner is a function that determines how to summarize the data in each alignment period. Aligners include the sum, the mean, and so forth. Valid aligner choices depend on the kind and type of metric data a time series stores. That is, aligner choice depends on the MetricKind and ValueType of the time series.

Some aligners both align the data and convert it from one metric kind or type to another. For more information on the available aligners, see Aligner in the API reference.

Secondary Aggregation

When you have multiple time series that already represent aggregations, like the examples illustrating the Group By option, you can then aggregate across them by choosing a Secondary Aggregator:

Field for secondary aggregation

Secondary aggregation reduces all the time series on the chart to a single time series.

Legend Template

In the Cloud Console, if you expand the aggregation options by clicking Show advanced options, in addition to displaying fields for the aligner, alignment period, and the secondary aggregator, a Legend Template field is displayed.

Sowing the location of the legend template field.

The Legend Template field lets you customize a description for the time series on your chart. These descriptions appear on the hover card for the chart and on the chart legend in the Name column.

By default, the descriptions in the legend are created for you from the values of different labels in your time series. Because the system selects the labels, the results might not be helpful to you. You can use this field to build a template for the descriptions.

The Legend Template field accepts the following:

  • Filters that refer to labels in your time series. To view all filters available for your time series, click Add a filter. After you select a filter, it's added to the text box and represented as an expression such as ${}. When the expression is evaluated, the value is pulled from the labels of a time series and inserted into the legend.

  • Plain text. If you supply only text, then the descriptions of the time series on the chart will be identical. However, you can combine text and filters.

For example, the following screenshot shows a template consisting of a plain text string and the filter expression ${}:

A template for a simple description.

In the chart legend, the values generated from the template appear in a column with the header Name and in the hover card:

Descriptions generated from a template.

You can create templates that use multiple strings and filters, but the display space available on the hover card is limited.