Create charts with Metrics Explorer

This document describes how you can explore metric data by building a temporary chart with Metrics Explorer. For example, to view the CPU utilization of a virtual machine (VM), you can use Metrics Explorer to construct a chart that displays the most recent data. If you want permanent charts, then you can create a chart by using Metrics Explorer and save it to a custom dashboard. An alternative is to create a custom dashboard, which can display charts, logs, incidents, and other content, and then use the dashboard interface to add charts to that dashboard. For information about custom dashboards, see Create and manage custom dashboards.

You can create simple charts, such as those that chart a single metric type, and complex charts, such as those that chart multiple metric types. After you create a chart with Metrics Explorer, you can discard it, save it to a custom dashboard, save its configuration, or share it.

The following screenshot shows a single metric type—the CPU Utilization of a VM instance—charted on the Metrics Explorer page:

Metric charted using Metrics Explorer.

The previous screenshot shows multiple lines, each line shows the average CPU utilization for all VMs in a specific zone.

Chart a single metric type

To configure a chart to display a single metric, do the following:

In the Google Cloud console, select Monitoring, and then select Metrics Explorer, or click the following button:
Go to Metrics Explorer
Specify the data to display on the chart. You can use a menu-driven interface, Monitoring Query Language (MQL), PromQL, or you can enter a Monitoring filter:
Menu-driven interface
1. Select the time series data that you want to view:
  1. In the Select a metric pane, expand the Metric menu and then use the menus to select a resource type and metric type. For example, you might make the following choices:
    
    In the Active resources menu, select VM instance.
    
    In the Active metric categories menu, select uptime_check.
    
    In the Active metrics menu, select Request latency.
    
    Click Apply.
    
    To limit the number of choices in the menus, enter the metric or resource name in the filter bar. For example, to chart the request latency for a VM instance, you might enter "latency".
    
    After you make your selections, the title of the pane changes. For example, if you made the previous suggestions, the pane title becomes Request latency.
  2. Optional: To specify a subset of data to display, select Add filter and complete the dialog. For example, you can view data for one zone by applying a filter. You can add multiple filters. For more information, see Filter charted data.
  For more information, see Select the data to chart.
2. Group and align time series:
  - To display every time series, on the Group By entry, click Delete grouping.
  - To combine time series that have the same label value, expand the Labels menu and select label values. You can also change the value of the Grouping function. For example, a chart can display the average value of the time series, where the average is computed by zone.
  - Optional: To configure the spacing between data points, click More options and then use the Datapoint alignment fields.
  For more information about grouping and alignment, see Choose how to display charted data.
3. Optional: To display only the time series with the highest or lowest values, click Add sort and limit, and then complete the form.
MQL
1. In the toolbar of the Select a metric pane, select the button whose name starts with Code.
2. Select MQL in the Language toggle. The language toggle is in the same toolbar that lets you format your query.
3. Enter your query into the query editor. For example, to chart the CPU Utilization of the VM instances in your Google Cloud project, use the following query:
```
fetch gce_instance
| metric 'compute.googleapis.com/instance/cpu/utilization'
| group_by 1m, [value_utilization_mean: mean(value.utilization)]
| every 1m
```
  For more information about MQL, see the following documents:
  - Introduction to MQL
  - Using the code editor for MQL
PromQL
1. In the toolbar of the Select a metric pane, select the button whose name starts with Code.
2. Select PromQL in the Language toggle. The language toggle is in the same toolbar that lets you format your query.
3. Enter your query into the query editor. For example, to chart the average CPU utilization of the VM instances in your Google Cloud project, use the following query:
```
avg(compute_googleapis_com:instance_cpu_utilization)
```
  For more information about using PromQL, see PromQL in Cloud Monitoring.
Monitoring filter
1. In the toolbar of the Select a metric pane, click Help on the Metric menu, and then select Direct Filter Mode.
  
  A text box labeled Enter a Monitoring filter 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.
2. Enter a Monitoring filter.
3. Group and align time series:
  - To display every time series, on the Group By entry, click Delete grouping.
  - To combine time series that have the same label value, expand the Labels menu and select label values. You can also change the value of the Grouping function. For example, a chart can display the average value of the time series, where the average is computed by zone.
  - Optional: To configure the spacing between data points, click More options and then use the Datapoint alignment fields.
  For more information about grouping and alignment, see Choose how to display charted data.
Update the chart settings based on your selected metric type:
- For quota metric types, use the following settings:
  - In the toolbar, set the time control to be at least one week. Quota metrics typically report one sample per day.
  - In the Display pane, expand the Widget type menu and then select Stacked bar chart.
- For metric types that have a Distribution value type, ensure that the Widget type menu is set to Heatmap chart. For more information, see About distribution-valued metrics.
- For other metric types, use the Widget type menu to display how the data is shown. The Widget type menu lists all available widget types; however, some widgets might not be enabled. Consider a chart that displays multiple time series, and assume that each measured value is a double:
  - Line chart, Stacked bar chart, and Stacked area chart widgets are listed as Compatible. You can select any of these types.
  - The Heatmap widget is disabled because these widgets can only display distribution-valued data.
Optional: To change how the chart displays the selected data, use the options in the Display pane:
- To configure the chart to display in x-ray mode or to display statistics, click Analysis Mode.
- To compare current to past data, click Compare to Past.
- To add a reference threshold, click Threshold Line.
- To configure the name of a legend column, click Legend Alias.
- To configure Y-axis assignment, labels, or scale, use the Y-axis assignment, Y-axis labels, and Y-axis scale menus.

Chart multiple metric types

In some situations, you might want to display time series from different metric types on the same chart. For example, to compare the read and write loads on a VM, configure a chart to display the number of bytes read and the number of bytes written.

To chart multiple metrics, you must use the menu-driven interface. The other interfaces don't support charting multiple metrics.

To display multiple metrics on a chart, do the following:

In the Google Cloud console, select Monitoring, and then select Metrics Explorer, or click the following button:
Go to Metrics Explorer
Use the options in the Select a metric pane, to select the first metric type whose data you want to view. For information about these steps, see Chart a single metric type.

The title of the Select a metric pane changes to be the metric that you selected.
For each additional metric type, do the following:
1. Select Add query.
  
  The new Select a metric pane hides the previously configured queries.
2. In the Select a metric pane, use the menus to select a resource type and metric type. You can also use the menus to add filters, group time series, and set the alignment fields.
To view all of the metric types that you have configured, go to the toolbar of the pane that you are viewing and then select Collapse.

The following screenshot illustrates the Metrics Explorer display when there are two metric types charted:

$Example of Metrics Explorer with two metric types.$
Optional: In the Display pane, expand the Y-axis menu and configure which Y-axis is used for each metric type.

Chart a ratio of metrics

Monitoring the number of errors reported might be useful; however, it is more likely that you need to monitor the rate of errors. That is, you want to know how many errors occurred as measured against the total number of responses. To meet this requirement, you can configure a chart to display the ratio of two metrics. For references to examples and for information about anomalies that can occur when you chart ratios of metrics, see Ratios of metrics.

To display a ratio of metrics on a chart, do the following:

In the Google Cloud console, select Monitoring, and then select Metrics Explorer, or click the following button:
Go to Metrics Explorer
Specify the data to appear on the chart:
Menu-driven interface
1. Configure the numerator:
  1. In the Select a metric pane, use the menus to select a resource type and metric type. For information about these steps, see Chart a single metric type.
  2. Update the grouping fields and alignment parameters. By default, Metrics Explorer adds a grouping that averages all time series.
  3. Optional: Update the alignment parameters. To view the alignment parameters, click More options.
2. Configure the denominator:
  1. Select Add query.
    
    The new Select a metric pane hides the previously configured queries.
  2. In the Select a metric pane, use the menus to select a resource type and metric type.
    
    The numerator and denominator metric types must have the same metric kind. For example, if the numerator metric is a GAUGE metric, then the metric you select for the denominator must be a GAUGE metric.
  3. Ensure that the value of the Minimum alignment period field is the same for both metrics. To view the alignment parameters, click More options.
  4. Update the grouping fields.
    
    We recommend that the grouping fields for the denominator metric type matches the values set for the numerator metric type. For example, you might group both metric types by the zone label.
    
    You aren't required to use the same grouping for both metric typess; however, you can only group by labels that are common to both metric types.
  5. To view all of the metric types that you have configured, go to the toolbar of the pane that you are viewing and then select Collapse.
    
    Your numerator and denominator queries are shown.
3. Select Create ratio in the toolbar of the query pane, and then complete the dialog.
  
  After you create the ratio, three queries are shown:
  - A/B Ratio identifies the ratio query.
  - A identifies the query for the numerator.
  - B identifies the query for the denominator.
  The following example illustrates a ratio that compares the sum of the bytes written to disk per zone, to the total number of bytes written to disk:
  
  $Example of a ratio of metrics.$
4. Optional: To switch the numerator and denominator metrics, do the following:
  1. Click Expand on the toolbar for the query whose name starts with A/B.
  2. Expand the Numerator and denominator menu and make a selection.
MQL
1. In the toolbar of the Select a metric pane, select the button whose name starts with Code.
2. Select MQL in the Language toggle. The language toggle is in the same toolbar that lets you format your query.
3. Enter your query into the query editor. MQL lets you compute a ratio of two different metrics, and it lets you filter a single metric by a label and then compute the ratio. The following query computes the ratio of responses with a value of 500 to the total number of responses:
```
fetch https_lb_rule::loadbalancing.googleapis.com/https/request_count
| {
    filter response_code_class = 500
  ;
    ident
  }
| group_by [matched_url_path_rule]
| outer_join 0
| div
```
  For more information about MQL, see the following documents:
PromQL
1. In the toolbar of the Select a metric pane, select the button whose name starts with Code.
2. Select PromQL in the Language toggle. The language toggle is in the same toolbar that lets you format your query.
3. Enter your query into the query editor. For example, to chart the ratio of average latency of your my_summary_latency_seconds metric, use the following query:
```
sum without (instance)(rate(my_summary_latency_seconds_sum[5m])) /
sum without (instance)(rate(my_summary_latency_seconds_count[5m]))
```
  For more information about using PromQL, see PromQL in Cloud Monitoring.
Monitoring filter
Not supported.

Save a chart for future reference

Metrics Explorer lets you create a chart that you can use to explore a metric. However, the charts created by this tool aren't persistent. When you navigate away from the Metrics Explorer page, the chart is discarded.

To save a chart you've configured with Metrics Explorer for future reference, add the chart to a custom dashboard or save the chart's URL:

To add the chart to a custom dashboard, do one of the following:
- If you use the Google Cloud console to manage your custom dashboards, then select Save Chart in the Metrics Explorer toolbar, and complete the dialog. You can save the chart to an existing custom dashboard or you can create a dashboard.
- If you use the Cloud Monitoring API to manage your custom dashboards, then update the JSON file that defines the dashboard and its contents. To access the JSON representation, click JSON Editor in the chart toolbar.
  
  For detailed information about using the API to manage your custom dashboards, see Create and manage dashboards by API.
To keep a reference to the chart configuration, save the chart URL. Because the chart URL encodes the chart configuration, when you paste this URL into a browser the chart you configured is displayed.

To obtain the chart's URL, click Link in the chart toolbar.

Save a chart's configuration

When you manage custom dashboards by using the Cloud Monitoring API, you can use Metrics Explorer to help you construct the data you provide to the API:

To generate the JSON representation for a chart that you plan to add to a dashboard, configure the chart with Metrics Explorer. You can then use options within Metrics Explorer to view and copy the chart's JSON representation.
To identify the syntax for a Monitoring filter, which is used with the Cloud Monitoring API, use the menu-driven interface of Metrics Explorer to configure the chart. After you select the metric and filters, switch to direct filter mode to view the equivalent Monitoring filter.

Save the data displayed by the chart

To save the data displayed by the chart to your local system, click Download CSV.