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:

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 (also called the 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 metric types 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:

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.

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

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

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.

• For information on view options, including outlier mode, see Setting View Options.
• For more information about interacting with the chart itself, see Working with Charts.

Filtering

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 removes some data from the chart by excluding time series that don't meet the filtering criteria. 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:

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.

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

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:

  

  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:

  

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

  

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:

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

Grouping

You can reduce the amount of data returned for a metric by combining data from similar time series.

Like filtering, grouping is way to reduce the amount of data you are manipulating. Filtering works by excluding some time series, and grouping works by identifying sets of time series that all meet some criterion and then combining, or aggregating, the members of the sets together.

Grouping is done on the basis of labels. When you click in the Group By field you get the same labels that are available for filtering.

The Group By option lets you group time series by resource and metric labels, and then combine the data within those groups. This creates a single new time series for each combination of group-by values, and the new time series represents all the members of the group.

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.

Group By chooses a default aggregation function based on the type of data being grouped, but you can change this selection. See Aggregation for information about other choices.

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

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 a chart that results from grouping the time series by zone:

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:

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:

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:

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.

Note: If you only delete the group-by labels, your chart will display a single line representing all of the data after the aggregation has been applied. To undo grouping, you must remove the group-by labels and reset the aggregation to none.

Aggregation

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.

Note: Time series must be aligned before they can be aggregated. Both the Aggregator and Group by options use a default alignment strategy, but you can change this. See Alignment for more information on this.

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.

The following screenshot shows the result of filtering for those time series originating from a Google Kubernetes Engine container and having a name that starts with d:

If you simply aggregate this data, say by sum, it is reduced to a single time series, which represents the sum of the values in each summed time series. The following screenshot shows the result:

There are multiple time series originating from containers with names that start with d. We can also group these time series by the value of one or more labels, and then aggregate over those resulting groups. This results in a a time series for each group. The following screenshot shows the result of grouping the filtered time series by machine image, using the default sum aggregation for 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.

Alignment

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, Stackdriver does it automatically, by using default values. You can override these defaults by using the alignment options, Aligner and Alignment Period:

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:

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

The following screenshot shows several time series that result from grouping a filtered set of data. The use of grouping requires aggregation; each group of lines is agregated into one. The following screenshot shows time series grouped by zone:

The following screenshot shows the result of using secondary aggregation to find the mean value across the grouped time series:

Legend template

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, these descriptions 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:

• Plain text.
• Variables that represent labels in your time series. The available labels depend on the time series you are charting, but the variable syntax generally look similar to this: ${resource.labels.project_id}. The ${} notation causes the variable to be evaluated in your description.

If you supply only text, then the descriptions of the time series on the chart will be identical. Using variables lets you pull values from labels in the time series into the description.

If you know the variable names, you can manually type them into the template field. You can also select variables for the available labels by using the + Add a filter widget in the field. This approach ensures that the variable syntax is correct.

The following screenshot shows a template consisting of a string and a single variable:

In the chart legend, the values generated from the template appear in a column with the header Name. The values also appear on the hover card.

The following screenshot shows the Name values and hover card that result from the template:

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

Hiding the additional options

To hide the Secondary Aggregation and Aligner options, click Hide advanced 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.