Selecting metrics

You define a chart by specifying both what data should display and how the chart should display it. To specify metrics to display, click the Metric tab on the chart-definition page.

The following screenshot shows the metric-selector tab:

Chart definition: metric-selection tab

The metric is specified in the Find resource type and metric field.

Choosing a metric

To populate the chart, you must specify at least one pair of values, the metric type (or metric descriptor, or just metric) and a monitored resource type (or monitored resource, or just resource). A monitored resource effectively specifies a subset of the time series data of a metric type.

Monitoring has many predefined metrics and resources available, and you can specify custom metrics as well. For more information on the predefined metrics types and monitored resources, see the lists of metrics and monitored resources. You can also define your own metrics and select them for charting; see Using Custom Metrics for more information.

When specifying a metric, the UI restricts the metric types and resources you can choose to those that currently have metric data in any project in your Workspace. The vast majority of metrics and resources will have no data in your project and will not appear as options.

You can specify more than one metric for a chart by using the Add metric option.

The metric-specification field

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:

Metric search lists

You can select an entry in two ways:

  • By selecting entries from the lists.
  • By typing directly to search the lists for matching candidates, including custom metrics.

To search for custom metrics, type custom in the search box.

The following screenshot shows the incomplete search term logg with the possible completions available for selection:

Searching metric space

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.

Tooltips for metric space

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 specifed metric on the Metric tab. The following screenshot shows the Metric tab after a metric has been specified:

Additional selection options

Based on the selected metric alone, with no other configuration, the following screenshot shows the resulting chart:

Chart with a metric selected

This chart contains more data that can be displayed; charts are limited to 300 displayable lines. The chart provides a notice that there is too much data to display, and suggests using outlier mode, one of the choices on the View options tab, which greatly reduces the amount of data to display.

However, you can also use the additional metric-configuration options to make the data set more manageable. These techniques make the charts more useful for diagnostics and analysis, and they increase the performance and responsiveness of the user interface itself.

Additional configuration

The rest of this section covers additional metric configuration.


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. Filtering lets you restrict the number of time series from your chosen metrics that contribute data. This results in fewer lines on the chart that displays this metric, which 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.

When you click in the Filter field, a panel containing lists of criteria by which you can filter appears. In broad strokes, you can filter by resource group, by name, by resource label, 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 a 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

With a zone="starts_with("asia-east1")" or zone=~"asia-east1.*" filter in place, the chart shows only the time series with data from one of the asia-east1 zones:

Displaying filtered time series


The Group By option lets you group time series by resource and metric labels, and then aggregate the data within those groups. This creates a single new time series for each group-by value, and the new time series represents all the members of the group. This reduces the number of lines on the chart displaying the metric, which can improve the performance of the chart.

Suppose, for example, you want to examine logging load but only at a regional level; that is, you don't care about the number of entries from specific servers. You can group time series by zone, and then chart the total, average, or other measure for each zone.

The default option for reducing a group of time series to one is to sum them. You do not set this manually, but you can change it; see Aggregation for more information about other choices.

The following screenshot shows a grouping by zone. The choice of sum under Aggregation is the default.

Grouping time series

This creates a new time series for each zone, with values computed from the sum of all the values for individual time series in that zone.

You can group by multiple labels, as well. When you group by multiple labels, you get a time series for each combination of labels. The order in which you specify the labels does not matter.

The following screenshot shows the chart that results from grouping the time series by zone:

Displaying grouped time series

You can group by multiple labels. For example, if you change the group-by choice from zone to severity, you see one time series for each logging severity level. The following screenshot shows all of the resulting time series:

Time series for log severity

If you group by both zone and severity, you get one time series for each pair of zone and severity-level values. The following screenshot shows a sample of such time series:

Time series for log severity and zone

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 chart at once. In this example, grouping by either zone or severity produces tractable amounts of data, but grouping by both results in more data than the chart can handle, as seen in the following screenshot:

Chart showing group-by for two labels

Removing group-by conditions

To remove a group-by condition, you must:

  1. Delete the group-by labels.
  2. Set the aggregation method back to none.


The Aggregation option lets you combine time series based on common statistics. This results in fewer lines on the chart displaying the metric, which can improve the performance of the chart.

Click in the field to see a list of the available aggregation options. These are the computations, or reducers, that can be used to combine the time series. The following screenshot shows some of the reducers available for the specified metric:

Aggregation choices

The reducers available 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.

When used without filtering or grouping, aggregation is applied across all the time series in a metric, reducing them to a single time series consisting of the mean, sum, or other measure as calculated across all the time series. For more information on aggregation, see Aggregation in the API reference.

You can also use aggregation in conjunction with the Filter and the Group By options.

The Group By option automatically applies aggregation to compute statistics within each group. The lines on a Group By chart already represent aggregations. By default, Group By uses the sum aggregation choice. You can choose any of the other aggregation options for a Group By label.

Filtering reduces the number of time series in the selected metric to those that meet some set of criteria. You can then apply aggregation to those lines. As with the unfiltered metric, aggregation of a filtered metric will reduce all of the lines to one that reflects the chosen aggregation statistic

The following screenshot shows the result of filtering for time series containing data from any of the us-central1 zones:

Example with filtering

Even after filtering, this chart still has a lot of data on it. If you simply aggregate this data, say by sum, it is reduced to a single line indicating the number of log entries written by servers in the us-central1 zones. The following screenshot shows the result:

Example with aggregated filtering

The total number of log entries is not a very granular measure. To see, for example, the numbers of the different types of log entries being written, group the log entries by severity. The following screenshot shows the result, using the default sum aggregation for grouping:

Example with grouped filtering

In this case, different severity classifications are aggregated into separate lines, regardless of which of the filtered serves it originates from. It is clear that most of the entries being written are of DEFAULT severity.

Below the Aggregation option is Show more options. Clicking this bar opens an additional configuration panel:

Additional aggregation options

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 aggregation statistic. This further reduces the number of lines on the chart displaying the metric, which helps performance.

This screenshot shows non-idle CPU usage statistics, grouped by instance ID and summed:

Per-instance summed non-idle CPU usage

This specification shows the individual lines representing CPU usage for each VM, filters out those in the idle state, and sums the results per instance. This gives you the total per-instance CPU utilization for each instance. You can then apply secondary aggregation to compute the average across these totals:

Mean summed non-idle CPU usage


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.

When a time series is aligned, some technique must be chosen for creating a value for the time series at each alignment interval, for example, the mean response time per alignment interval. The default aligner used with the Group By and Aggregation options is sum.

The Aligner option lets you change the default aligner for your selected metric to another valid option.

Example of aligner choices

Aligner choices

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 temporally and convert it from one metric kind or type to another.

For more information on the available aligners, see Aligner in the API reference.

Alignment intervals

Stackdriver Monitoring uses two built-in sets of alignment periods, providing two different granularities. Each set determines the duration of the alignment period for different data-reporting periods:

Fine-grained alignment intervals

Data-reporting period Alignment interval
Less than 23 hours 1 minute
Greater than 23 hours 5 minutes
Greater than 6 days 1 hour

In this case, alignment intervals are short, and they are used for for longer periods of time. This results in a greater number of alignment points for a reporting period than with the coarse-grained intervals.

Coarse-grained alignment intervals

Data-reporting period Alignment interval
Less than 20 minutes 1 minute
Greater than 20 minutes 5 minutes
Greater than 5 hours 30 minutes
Greater than 23 hours 2 hours
Greater than 6 days 1 day
Greater than 23 days 2 days

In this case, alignment intervals are longer in general, and they are used for shorter periods of time, resulting in fewer total alignment points for a reporting period than with the fine-grained intervals.

Different chart types use different granularities, and time series are realigned, for example, when you zoom in or out, which changes the data-reporting period. Users cannot choose the granularity or override the alignment-interval value.

Hiding the additional options

To hide the Secondary Aggregation and Aligner options, click Hide more options at the bottom of the pane. This does not clear any selected options. If you change or remove grouping, for example, forgotten choices for these hidden options can cause unexpected effects.

Was this page helpful? Let us know how we did:

Send feedback about...

Stackdriver Monitoring
Need help? Visit our support page.