This document describes how to configure a temporary chart that displays the time-series data collected by your project. Metrics Explorer can display only numeric time-series data.
Select the data to display
There are different ways that you can specify the time series to display when you use Metrics Explorer:
A menu-driven interface where you specify time series by selecting a resource type, a metric type, and filters. The menu-driven interface provides you with your valid choices, eliminates the need to know a specific syntax, and it lets you chart multiple metric types:
A metric type identifies the measurements to be collected from a resource. It includes a description of what is being measured and how the measurements are interpreted. A metric type is sometimes referred to as a metric. An example of a metric is "CPU utilization". For conceptual information, see Metric types.
A resource type specifies from which resource the metric data is captured. Resource type is sometimes called the monitored resource type or the resource. An example of a resource is a "Compute Engine virtual machine (VM) instance". For conceptual information, see Monitored resources.
A Monitoring Query Language (MQL) interface where you specify time series by entering MQL statements. The MQL interface supports a Query Editor with syntax checking.
This document doesn't describe how to use MQL. For information about MQL syntax, see Introduction to Monitoring Query Language (MQL).
Because MQL is more expressive than the other interfaces, an MQL query that you enter is discarded when you switch to a different interface.
A text interface where you specify time series by entering a Monitoring filter. Monitoring filters must be used when the time series that you want to chart can't be represented with the resource and metric model. For example, to count the number of processes running on a VM, you must enter a Monitoring filter. For more information, see Direct Filter Mode.
Because Monitoring filters can describe time series that can't be represented with the resource and metric model, your configuration might be discarded when you switch to a different interface.
To use menus to specify time series to display, do the following:
- In the Cloud console, select Monitoring
or click the following button:
Go to Monitoring
In the navigation pane, select Metrics Explorer .
Select the Configuration tab:
Expand the Select a metric menu.
(Optional) To reduce the number of options shown in the menu, enter the metric or resource name in the filter_list Filter bar. For example, by entering
utilyou restrict the menu to show entries that include
util. Entries are shown when they pass a case-insensitive contains test.
To view a list of all metrics, even those without recent data, set the Show only active resources & metrics toggle to disabled. By default, the this toggle is set to enabled so only metrics and resources with data are shown in the menus.
In the Resource menu, select the resource from which the metric data is captured.
When a metric isn't written against a resource, select Unspecified.
In the Metric category menu, select the category of the metric.
The category is typically the first term following the metrics prefix. For example, for the metric
compute.googleapis.com/instance/utilization, the category is
In the Metric menu, select the metric to chart.
For example, to chart the CPU utilization of a virtual machine, you might do the following:
utilin the filter_list Filter bar.
- In the Resources menu, select VM instance.
- In the Metric categories menu, select Instance.
- In the Metrics menu, select CPU utilization and then click Apply.
After resource type and metric are 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:
The previous 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 Settings. For more information, see Set 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.
(Optional) Add filters to restrict which time series are shown. For more information, see Filter charted data.
Direct filter mode
Use direct filter mode when you are interested in charting any of the following:
- A service-level objective (SLO).
- The count of processes running on virtual machines (VMs).
- A custom metric for which you don't yet have data.
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.
For example, the following expression results
in a chart displaying a count of processes whose name includes
You can also use Monitoring filters to identify time series
by their resource and metric type. The following expression results in a
chart displaying the count of log entries for all Google Cloud virtual
machine instances in the
metric.type="logging.googleapis.com/log_entry_count" resource.type="gce_instance" resource.label."zone"="us-east1-b"
To enter a Monitoring filter, do the following:
- In the Cloud console, select Monitoring
or click the following button:
Go to Monitoring
- In the navigation pane, select Metrics Explorer .
- Select the Configuration tab.
Click help_outline Help on the Select a metric menu, and then select Direct Filter Mode.
On the page, a text box is shown. If you selected a resource type, metric, or filters before switching to Direct Filter Mode mode, then those settings are shown in the text box.
Enter a Monitoring filter expression in the text box. For syntax information, see the following documents:
When you use direct filter mode and no data is available that satisfies the filter, an error is shown. Common error messages include
Chart definition invalidand
No data is available for the selected timeframe.
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. When you apply filters, you might reduce the number of lines on the chart, which can improve the performance of the chart.
The remainder of this section applies to configuring a chart when using a menu-driven interface. This section isn't applicable to MQL and Monitoring configurations, which include filter statements.
When you supply multiple filtering criteria, the corresponding chart shows
only the time series that meet all criteria, a logical
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 Configuration tab, click Add filter and then specify the filter label, the comparison, and the value or range of values:
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 filter_list text area. When you enter text, the menu lists only those entries that contain the entered text.
The following screenshot shows the known filter-by labels for a specific metric:
Click Comparison and then select an entry from the menu. You can choose between four operators: equals,
=, not equals,
!=, regular expression match,
=~, and regular expression does not match,
Click Value and then do one of the following:
For a direct comparison,
!=, select the value from the menu or enter a value and click Done. Entered values can be simple values such as
us-central1-a, or you can create a filter string that begins with
ends_with. For example, to display data for any
us-central1zone 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, when a monitored resource isn't generating data for the selected metric, you must enter a value for the label.
The following screenshot shows the value menu that is displayed for a particular project when the
zoneresource label is selected:
For a regular expression comparison,
!=~, enter a RE2 regular expression into the Value field and click Done. For example, the regular expression
To match any US zone that ends with “a”, you could use the regular expression
You can't use regular expressions to filter the
For example, to view only the time series from one of the
us-central1zones, apply a
You can specify multiple filter criteria, and you can use the same label
multiple times. These capabilities let you specify a filter for a range of
values. All filter criteria must be met; they constitute a logical
AND. For example, the following a configuration that
you can use both
strings to show only “a” zones in the US:
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 within a time series, and combining different time series together. For a detailed explanation of aggregation, see Filtering and aggregation: manipulating time series.
- For information on view options, including outlier mode, see Set View Options.
- For more information about interacting with the chart itself, see Explore charted data.
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 data 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 type of data being displayed determines the default aggregator; 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 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
The data points in each time series are computed
from the sum of all the values for individual time series for a specific
You can group by multiple labels. When you have multiple grouping options, the aggregator is applied to the set of time series that have the same values for the selected labels.
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
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:
- Delete the group-by labels.
- Set the aggregator to
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.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 data points within the alignment period.
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.
When the Aligner field
has a value of mean, then each point on the chart is the average of
all points in an alignment period.
However, if you now 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.
While most of the aligners perform common mathematical functions, some 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 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 unit of the original time series is MiB and the unit of the alignment period is second, then the chart has a unit 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
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
For comparison, the following screenshot illustrates the effect of changing
the period from
1 minute to
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, which has a smoothing effect on the plotted data.
When you have multiple time series that already represent aggregations, you can reduce all the time series on the chart to a single time series by choosing a Secondary Aggregator. For example, if you group data by zone, your chart shows one time series for each zone. To create a chart with a single time series, use the secondary aggregation fields.
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:
The following screenshot shows the result of using secondary aggregation to find the mean value across the grouped time series:
The Legend Template field lets you customize a description for the time series on your chart. These descriptions appear on the tooltip 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. To build a template for descriptions, use this field.
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 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
For example, the following screenshot shows a legend template that contains
plain text and the expression
In the chart legend, the values generated from the template appear in a column with the header Name and in the tooltip:
You can configure the legend template to include multiple text strings and templates; however, the display space available on the tooltip is limited.