Selecting data to chart

This page describes how to specify what data a chart should display. For information on configuring the style of a chart, see Setting view options.

Selecting the data to display

To populate the chart, you must specify at least one pair of values:

• A metric type that identifies the measurements that can be collected from a monitored resource. It includes a description of what is being measured and how the measurements are interpreted. The metric type is sometimes called metric. For conceptual information, see Metric types.

• A monitored resource specifies from which resource the metric data is captured. The monitored resource 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

Dashboard editor

When you drag a widget from the Widget library to the graph area, a chart is displayed with a preselected resource type and metric:

There are different ways you can specify the data to chart:

• To quickly configure a chart, use the Basic mode. This choice has minimal configuration options. A basic configuration can always be represented in the other modes. For details, see Using the Basic or Advanced mode.

• To have access to all chart configuration fields, use the Advanced mode. This mode provides access to most aggregation fields. For details, see Using the Basic or Advanced mode.

  Note: You might see an error message if you use the Advanced mode to configure the chart and then select the Basic mode. These are displayed when the configuration you select in the Advanced mode cannot be represented with the options available in the Basic mode.

• To configure a chart using a query language, use the MQL mode. With this mode, you have access to the Query Editor. If you use MQL, that configuration cannot be represented by the other modes. For information about MQL, see Introduction to MQL.

  Note: MQL queries can't be represented by the Basic or Advanced modes. If you configure a chart using MQL, don't access the Basic or Advanced modes if you want to preserve that configuration. You have the option to copy the query into a clipboard.

Using the Basic or Advanced mode

The Resource type menu lists every monitored resource for which there is metric data. The Metric menu is determined by the selection for the Resource type.

• To find a specific entry in a menu, use the scrollbar or enter text into the menu's Filter area. When you enter text, the menu entries are limited to those that include the entered text.

  The following screenshot illustrates the expanded menu for the Metric field. The filter bar contains the text lat, so this menu only lists entries that include that string:

  

  Note that in the previous screenshot, the metric Late Boot Validation is highlighted. When your pointer is placed over an entry a pane opens and displays detailed information about that metric. As illustrated, this pane lists, among other things, the metric kind, value type, and the description field.

If you want to access a resource type or metric that doesn't yet have data, then you need to change the default behavior:

• To be able to select any resource type, expand the Resource type menu and then uncheck Only show active.

• To view all metrics for the selected resource type, even those metrics without data, expand the Metric menu and then uncheck Only show active.

• To be able to select any metric, click Close on the Resource type menu and then find the entry of interest. By clicking close on the resource type, the Metric menu includes all metrics.

• To view or edit the resource type, metric, and filter settings as used by the Cloud Monitoring API, in the Resource type menu, click Direct filter mode.

Legacy dashboard editor

To select a metric, use the Find resource type and metric field to choose one monitored resource and one metric type. You can specify them in either order. To begin, click the hint text in the field to display a list that contains one or two sections, depending on previous selections. The sections are indicated by headers, Resource type and Metric, as seen in the following screenshot:

To complete the resource type and metric selections, do one of the following:

• Enter or select values from the lists.

  The lists are filtered based on any text you enter. For example, if you type CPU Usage, then every member of the list contains CPU and usage.

  Because there fewer resource types than metrics, select the Resource type first. If your resource type isn't displayed in the short list, click See all. After you select the resource type, the metric list is automatically filtered to display only relevant metrics.

• Enter a metric filter by using the following procedure:

  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:

     

     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="logging.googleapis.com/log_entry_count" 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.

To view details of a menu entry, place your pointer over the item. For information on descriptors for metric types or monitored resources, see the metrics list or the monitored resource list.

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. To reduce the amount of data, you can apply filters, apply aggregation, or use outlier mode.

Note: You cannot select metric types with values of type String from the console. String-valued data can't be displayed on charts or used in alerting policies. To retrieve data for these metric types, you must use a method in the API, like timeSeries.list.

Filtering the 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.

Dashboard editor

This section describes how to configure a filter when you select the the Basic or Advanced mode. If you select the MQL mode, then use the Query Editor.

Typically, you can filter by resource group, by name, by resource label, by zone, and by metric label.

To add a filter, 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:

   

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, !=~:

   

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:

     

   • If you selected a regular expression comparison, =~ or !=~, then 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:

     

Note: You can edit a filter. To edit a filter, double-click the filter chip to place it in edit mode. After the changes are complete, press enter. The styling of the filter briefly changes as your changes are saved.

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:

Legacy dashboard editor

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 specific metric:

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.

Note: If a monitored resource isn't generating data for the selected metric, then a filter's Values menu won't contain information for that monitored resource. For example, assume your project contains one VM instance that is stopped. Assume that you create a chart for the CPU usage of a VM instance. Next, you add a filter and select instance_id. In this case, the Values menu, which lists all of the available instances, is empty. However, you can manually enter the value and then select Apply.

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 !=~, then enter a RE2 regular expression as the value. For example, the regular expression us-central1-.* matches any us-central1 zones:

  

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

  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:

Choosing how to display the data

After the time series data is selected, the next step is to determine how that data is displayed. For example, do you want to display each time series or do you want to combine time series together?

You specify how the data is displayed by configuring the aggregation options. Aggregation consists of aligning time series data and then combining different time series together. Combining time series is optional.

For a detailed explanation of aggregation, see Filtering and aggregation: manipulating time series.

Aligning data

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 (Dashboard editor), or the Period field (Legacy dashboard editor), 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 Alignment function field (Dashboard editor), or the Aligner field (Legacy dashboard editor), 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 access the alignment fields, do the following:

Dashboard editor

• Basic mode: All alignment fields are preconfigured.

• Advanced mode: All alignment options are accessible after you select the resource type and metric. Default values for these fields are provided; however, you can modify the selections.

• MQL mode: All alignment options are available.

Legacy dashboard editor

After you select the resource type and the metric, the alignment period is displayed on the main panel:

To view the alignment functions, 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:

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

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.

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

Dashboard editor

To group and combine time series, do one of the following:

• Basic mode:

  1. Determine how to group time series:

     • To display every time series, leave Grouped unchecked.
     • To group time series by label values, check Grouped and then use the Group by menu to select the labels for grouping. After you make your selections, click OK.

  2. Determine how to combine data points:

     • If the radio buttons only list percentiles, then you've selected a metric that has a distribution value. Use the radio buttons to select which percentile from the distribution to view.

     • If the radio buttons list mean, min, and max, then you've selected a metric with a numerical value. Use these buttons to specify how data points are combined as part of the charting process. To understand how these combiners work, assume that a chart can display 60 data points and assume that the data rate is 1 point per minute. If you display one hour of data, then the chart can display every point. However, if you want to display 3 hours of data, you have to reduce 180 data points to 60, which is the number of points the chart can display. One way to reduce the data is to average three adjacent samples, another is to take the minimum.

• Advanced mode:

  • To combine all time series into a single time series, ensure Group by is empty and select how the time series are combined by using the Group by function menu.

    Note: You must use this option if you are displaying time series on a heatmap chart. For more information, see Charting distribution metrics.

  • To display all time series, do one of the following:

    • Ensure Group by is empty and select none for the Group by function.
    • Click the Group by menu and select Add all, and then select a Group by function. For metrics which store a numerical value, the choice of group-by function might not produce a visibly different chart.

  • To group time series by specific label values, click Group by and select the labels for grouping. To specify how the time series are combined, select a function by using the Group by function menu.

• MQL mode:

  For information about Monitoring Query Language, see Using the Query Editor.

The following screenshot shows a grouping by user_labels.version with the group-by function set to the default value of sum. 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:

Legacy dashboard editor

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.

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

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:

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 group-by function (Dashboard editor) or aggregator (Legacy dashboard editor) 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:

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 group-by function (Dashboard editor) or aggregator (Legacy dashboard editor), the charted time series only contains required labels, such as the project identifier, and the labels specified by the grouping.

Removing group-by conditions

Dashboard editor

To remove all group-by conditions, do one of the following:

• Basic mode: Uncheck Grouped.

• Advanced mode: Do the following:

  1. In the Group by menu, click Remove all and then click OK.
  2. In the Group by function menu, select none.
  Note: When using the Advanced mode, if you only delete the group-by labels, then your chart displays a single line that represents all of the data after the group-by function has been applied. To undo grouping, you must remove the group-by labels and reset the group-by function to none.

• MQL mode: Delete grouping commands.

  For information about Monitoring Query Language, see Using the Query Editor.

Legacy dashboard editor

To remove a group-by condition, you must:

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

Note: If you only delete the group-by labels, then your chart displays a single line that represents all of the data after the aggregator has been applied. To undo grouping, you must remove the group-by labels and reset the aggregator to none.

Secondary aggregation

Dashboard editor

• Basic and Advanced modes: The Dashboard editor determines how to map your aggregation selections to the primary and secondary aggregation fields specified by the Cloud Monitoring API by using the following information:

  • Widget type
  • Kind of metric
  • Value type of the metric
  • Which mode is being used to configure the widget

  To determine this mapping for charts on custom dashboards, you can retrieve the dashboard configuration by using the gcloud command-line tool. For more information, see Listing dashboards.

• MQL mode: These fields accessible.

Legacy dashboard editor

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 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:

What's next

• For information on monitored resources, see monitored resources.

• For a list of predefined metrics, see metrics.

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

• For information on how to use the legend template, see Configuring the legend template.

• For information on view options, including outlier mode, see Setting View Options.

• For more information about interacting with the chart itself, see Exploring charted data.