Selecting metrics when using Metrics Explorer

Metrics Explorer is a stand-alone charting tool that lets you build charts for any (numeric) metric collected by your project. This page describes how to configure Metrics Explorer by using its Configuration tab. If you use Monitoring Query Language (MQL), the concepts on this page apply; however, you must use the syntax defined in the Introduction to Monitoring Query Language (MQL).

For information on configuring the style of a chart, see Setting View Options.

Select the data to display

To specify the metrics to display when using Metrics Explorer, you specify values for a metric and a resource type:

  • The metric field identifies the measurements to be collected from a monitored resource. It includes a description of what is being measured and how the measurements are interpreted. Metric is a short form of metric type. For conceptual information, see Metric types.

  • The resource type field specifies from which resource the metric data is captured. The resource type is sometimes called the monitored resource type or the resource. For conceptual information, see Monitored resources.

Monitoring has many predefined metric types and monitored resources available, and you can create custom metrics as well:

  • For information on predefined metrics types, see the Metrics list. Metrics are listed by the type of service. For example, the Google Cloud metrics page contains a series of tables, one for each Google Cloud service.

  • For information about monitored resource types available, see Monitored resource list.

  • For information on defining your own metrics, see Using custom metrics.

The metric-specification field

The metric is set by the values of the Resource type and Metric fields. You can complete these fields in any order, and both fields let you enter values or select entries from the menu:

  • To reduce the number of options displayed in a menu, enter a value on the filter bar. For example, if you enter cpu, then the menu only lists entries that include cpu. A case-insensitive test is used to determine if an entry is listed.

  • To get more information about an entry, place your pointer on the entry to activate the tooltip.

  • To enter a Monitoring filter, see Direct filter mode.

After resource type and metric pair is selected, the chart shows all the available time series for that pair. The following screenshot shows a chart after the resource type and metric are selected:

Display a 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, which greatly reduces the amount of data to display. To access the outlier mode controls, click Settings. For more information, see Setting view options.

You can also use the filtering and aggregation options to reduce the amount of charted data. These techniques make the charts more useful for diagnostics and analysis, and they increase the performance and responsiveness of the user interface itself.

Direct filter mode

Direct filter mode lets you enter an expression that Monitoring uses to identify the time series to be monitored. The expressions that you enter in direct filter mode are sometimes referred to as metric filters or Monitoring filters. The following illustrates an expression that causes Monitoring to display the log entries for all Google Cloud virtual machine instances in the us-east1-b zone:

metric.type="logging.googleapis.com/log_entry_count"
resource.type="gce_instance"
resource.label."zone"="us-east1-b"

Direct filter mode is useful when you want to identify the proper syntax for an API call or to verify that a {monitoring_name_short}} filter is properly formatted. It is also useful when you want to chart data that isn't represented by the resource and metric model. For example, the following expression results in a chart displaying a count of processes whose name includes nginx:

select_process_count("monitoring.regex.full_match(\".*nginx.*\")")
resource.type="gce_instance"

For information on the syntax required to monitor a service-level objective (SLO), see Retrieving SLO data. For general information, see Monitoring filters.

To enter a Monitoring filter, do the following:

  1. Expand the Resource type menu and select Direct filter mode.
  2. Enter a Monitoring filter expression in the text box.

    The text box is populated with the resource type, metric, and filter setting that you made before you changed to Direct filter mode

    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.

To return to the menu-driven interface, click Standard mode.

Filter charted data

You can reduce the amount of data to be charted by specifying filter criteria, applying aggregation, or by using outlier mode. Filters ensure that only time series that meet some set of criteria are used. If you apply filters, then there are fewer lines on the chart, and that can improve the performance of the chart.

If you supply multiple filtering criteria, then the corresponding chart shows only the time series that meet all of the criteria, a logical AND. Typically, you can filter by resource group, by name, by resource label, by zone, and by metric label.

To add a filter when you use the MQL tab, use the Query Editor to specify the filter.

To add a filter when you use the Configuration tab, click Add filter and then specify the filter label, the comparison, and the value or range of values:

  1. Click Label and then select an entry from the menu.

    To find a specific label, you can use the scrollbar or you can enter text into the Filter text area. When you enter text, the menu entries are limited to those that contain the entered text.

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

    Example of a list of filter labels.

  2. Click Comparison and then select an entry from the menu, or leave this at the default value. You can choose between four operators: equals, =, not equals, !=, regular expression match, =~, and regular expression does not match, !=~:

    List of filter comparators.

  3. Click Value and then do one of the following:

    • If you selected a direct comparison, = or !=, then select from the menu or click Edit and enter a value. Entered values can be simple values such as us-central1-a, or you can create a filter string that begins with starts_with or ends_with. For example, to display data for any us-central1 zone you could enter the filter string starts_with("us-central1"). See Monitoring filters for more information on filter strings.

      Because the menu entries are derived from the received time series, if a monitored resource isn't generating data for the selected metric, then you must enter a value for the label.

      The following screenshot shows the value menu that is displayed for a particular project when the zone resource label is selected:

      Example of a list of filter labels.

    • If you selected a regular expression comparison, =~ or !=~, then click Edit and enter a RE2 regular expression in the value. For example, the regular expression us-central1-.* matches all us-central1 zones.

      To match any US zone that ends with “a”, you could use the the regular expression ^us.*.a$.

      You can't use regular expressions to filter the project_id resource label.

      For example, if you want to view only the time series from one of the us-central1 zones, then apply a zone="starts_with("us-central1")" or zone=~"us-central1.*" filter:

      Displaying a filtered time series.

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. All of the filter criteria must be met; they constitute a logical AND. For example, the following a configuration that you can use both starts_with and ends_with filter strings to show only “a” zones in the US:

Example using multiple filters.

Choose how to display charted data

The section covers how to display the selected data by setting the aggregation fields. Aggregation consists of alignment of data points and the combining different time series together. For a detailed explanation of aggregation, see Filtering and aggregation: manipulating time series.

Group time series

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 by label values. The function defines how all time series within a group are combined into a new time series.

To add a grouping, click the text in the Group by text box, and then make a selection from the menu. The menu is constructed dynamically based on the time series data for the resource and metric you selected. Grouping and filtering use the same set of labels.

When you add the first label, 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 determines how the time series that have the same label value are combined into a single time series.
  • The chart displays one time series for each value of the label listed in the Group by text box.

If you group by multiple labels, then the aggregator combines those times series that have the same value for the specified labels.

If you don't specify a grouping option and do specify an aggregator, then that function is applied to all of the selected time series and results in a single time series.

For example, if the Group by field is set to user_labels.version and the aggregator is set to sum, then there is one time series for each value of the label 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. If 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.

When you specify grouping or if you select an aggregator, the charted time series only contains required labels, such as the project identifier, and the labels specified by the grouping.

Remove group-by conditions

To remove a group-by condition, you must:

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

Align time series

Alignment is the process of converting the time series data received by Monitoring into a new time series which has data points at fixed intervals. The process of alignment consists of collecting all data points received in a fixed length of time, applying a function to combine those data points, and assigning a timestamp to the result. That function might compute the average of all samples or it might extract the maximum of all samples.

The Alignment period specifies the minimum time interval to be used when aligning time series data. When there are too many data points to chart in the selected display period, then the alignment period is automatically increased so that every data point is represented. The default setting for this field is one minute.

For example, consider a metric with a sampling period of one minute. If a chart is configured to display 1 hour of data, then the chart can display all 60 data points. If the alignment period is set to 10 minutes, then the chart displays 6 data points. However, if you configure the chart to display one week of data, then there are too many points to display in the chart so the period is automatically modified. In this example, the modified alignment period is one hour.

The Aligner field specifies the function used to combine all the data points in an alignment period. Most of the aligners perform common mathematical functions. For example, if you select min, then the aligned data point is the minimum of all of the data points within the alignment period. A few of the aligners perform more complicated actions:

  • next older: To retain only the most recent sample within an alignment period, use the next older aligner. This aligner is commonly used with uptime checks and is a good choice when you only care about the most recent value.

    This aligner is valid only for gauge metrics.

  • percentile: To display a distribution metric on a plot type of line chart, stacked area chart, or stacked bar chart, you must select which percentile in the distribution to display. One way to specify this percentile is to select a percentile aligner. You can select the 5th, 50th, 95th, and the 99th percentiles. The aligned data point is determined by computing the specified percentile by using all of the data points in the alignment period.

    This aligner is valid only for gauge and delta metrics when they have a distribution data type.

  • delta: To convert a cumulative metric or a delta metric into a delta metric with one sample per alignment period, use this aligner. This aligner might result in data interpolation. For an example, see Kinds, types, and conversions.

    This aligner is valid only for cumulative and delta metrics.

  • rate: To convert a cumulative or delta metric into a gauge metric, use this aligner. If you choose this aligner, you can think of the time series being transformed as it was with a delta aligner and then divided by the alignment period. For example, if the units of the original time series is MiB and the units of the alignment period is seconds, then this choice of aligner results in a chart with the units of MiB/second. For more information, see Kinds, types, and conversions.

    This aligner is valid only for cumulative and delta metrics.

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

To view or modify the alignment function, click Show advanced options.

The following screenshot illustrates the CPU utilization of the Compute Engine VM instances in a particular Google Cloud project. In this image, the alignment fields are at the default values: the alignment function is set to mean and the alignment period is set to 1 minute:

CPU utilization of VM instances using default alignment settings.

For comparison, the following screenshot illustrates the effect of changing the period from 1 minute to 5 minutes:

CPU utilization of VM instances using default with a 5 minute alignment period

By increasing the period, the resulting chart has fewer points, decreasing from 60 points per time series to 10 points per time series. Each point on the chart is computed by averaging the time series points in an alignment period. By increasing the alignment period, more points are averaged together and this has a smoothing effect on the plotted data.

Secondary aggregation

When you have multiple time series that already represent aggregations, like the examples illustrating the Group By option, you can reduce all the time series on the chart to a single time series by choosing a Secondary Aggregator.

To view or modify the secondary aggregation settings, click Show advanced options.

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 aggregated into one. The following screenshot shows time series grouped by zone:

Showing a filtered time series that is grouped by zone.

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

Showing a secondary aggregation applied to previous example.

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, 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.

To access the legend template for a chart, in the Cloud Console, select the Advanced tab in the chart's configuration pane. The legend template is listed under the heading Additional options.

You can enter plain text and templates in the Legend Template field. When you add a template, you add an expression that is is evaluated when the legend is displayed.

To add a template, do the following:

  • Click Insert a template.
  • Select an entry from the menu. After you select an entry, a template is automatically added. For example, if you select response_code, then the template ${resource.labels.zone} is added.

For example, the following screenshot shows a legend template that contains plain text and the expression ${resource.labels.zone}:

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 configure the legend template to include multiple text strings and templates; however, the display space available on the hover card is limited.

What's next