This document describes how to configure a temporary chart that displays thetime-series data collected by your project. Metrics Explorer can displayonly numeric time-series data.

Select the data to display

To configure which time series to display on a chart, you canbuild a query by making selections from menus, or you can write a query.When you write a query, you select your query language and then you use aquery editor or a text-based interface:

• Prometheus Query Language (PromQL) queries specify time seriesand how those time series are grouped and aligned.The PromQL interface supports an editor with suggestions.

  It isn't generally possible to convert PromQL queries into formsthat can be used by the other interfaces. Your unsaved queries arediscarded when you switch to or from the PromQL tab.

• Monitoring filter queriesspecify the time series but don't include grouping or alignment statements.

  Any time series that Monitoring can chart can be specifiedby using a Monitoring filter. For example, to chart the numberof processes running on a VM, you must use aMonitoring filter that specifies a function.

  It isn't always possible to convert a Monitoring filterinto the form required by other interfaces. Therefore, your query mightbe discarded if you switch to a different interface.

Queries typically specify a metric type, a resource type, and filters:

• Ametric type identifies the measurements to be collected from aresource. It includes a description of what is being measuredand how the measurements are interpreted. Ametric type is sometimesreferred to as ametric. An example of a metric is "CPU utilization".For conceptual information, seeMetric types.

• Aresource type specifies from which resource the metric data iscaptured.Resource type is sometimes called themonitored resource type or theresource. An example of aresource is a "Compute Engine virtual machine (VM) instance".For conceptual information, seeMonitored resources.

PromQL queries include grouping and alignment statements. However, when youwrite a Monitoring filter or usemenus to select the time series to chart, you configure the grouping andalignment settings by using menus.

Build queries by using menus

Building queries by using menus is the default configuration. Typically, ifyou select a a metric and a filter, and then switch to a different interface,your selections are preserved and reformatted for that interface. That is,a query constructed by menus can be converted to a PromQL query.

You can return from the other interfaces to the menu-driven interface byselectingtuneBuilder. However, your query is discarded.That is, a PromQL query can't be converted into an equivalentmenu-driven form.

To build your query by using menus, do the following:

1. In the Google Cloud console, go to theleaderboard Metrics explorer page:

   Go toMetrics explorer

   If you use the search bar to find this page, then select the result whose subheading isMonitoring.

2. In the toolbar of the Google Cloud console,select your Google Cloud project. ForApp Hubconfigurations, select the App Hub host project or management project.

3. In the toolbar of the query pane, do the following:

   1. In theMetric element, expand theSelect a metric menu.

      TheSelect a metric menu contains features that help you findthe metric types available:

      • To find a specific metric type, use thefilter_listFilter bar.For example, if you by enterutil, then you restrict the menu toshow entries that includeutil. Entries are shown when they passa case-insensitive "contains" test.

      • To show all metric types, even those without data, clickdone Active. By default, the menusonly show metric types with data.

   2. Make a selection from theResources menu,theMetric categories menu, theMetrics menu, and thenclickApply.

      For example, to chart the CPU utilization of a Compute Enginevirtual machine, you might selectVM instance,Instance,CPU utilization, and the clickApply.

      TheResources menu lists the resource from which the data iscollected. When a metric isn't written against a resource,selectUnspecified.

   After the resource type and metric are selected, the chart showsall the available time series for that pair:

   

   The previous chart contains more data than can be displayed; charts arelimited to 50 displayable lines.The chart provides a notice that there is too much data to display. Toreduce the amount of data, in the query toolbar, use theSort & limit element. For more information, seeShow outliers.

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

4. Optional: Add filters to restrict which time series are shown. The nextsection describes the filtering options.

5. Optional: Configure how the time series are grouped and aligned. For moreinformation, seeChoose how to display charted data.

Filter charted data

Filters ensure that only time series that meet some set of criteria are charted.When you apply filters, you might reduce the number of lines on the chart,which can improve the performance of the chart. Another way that you can improvethe responsiveness of a chart is to configure aggregation options, and tosort and limit the number of time series that are displayed.For more information, seeShow outliers.

A filter is composed of a label, a comparator, and a value. For example,to match all time series whosezone label starts with"us-central1", youcould use the filterzone=~"us-central1.*", which uses a regular expressionto perform the comparison. There are four comparator operators:

• equals,=
• not equals,!=
• regular expression match,=~
• regular expression does not match,!=~

When you filter by the project ID or the resource container,you must use the equals operator,(=). When you filter byother labels, you can use any supported comparator.Typically, you can filter metric and resource labels, and byresource group.

When you supply multiple filtering criteria, the corresponding chart showsonly the time series that meetall criteria, a logicalAND.

To add a filter when using the menu-driven interface of the Google Cloud console,do the following:

1. In theFilter element, clickAdd filter, and make a selectionfrom the menu.

2. To change the comparison, select a value from theComparator menu.

3. In theValue field, enter or select a value:

   • For a direct comparison,= or!=, select the value from themenu or enter a value and clickOk. You can enter valuessuch asus-central1-a, or you can create a filterstring that begins withstarts_with orends_with.For example, to display data for anyus-central1 zone you could enterthe filter stringstarts_with("us-central1").SeeMonitoring filtersfor more information on filter strings.

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

   • For a regular expression comparison,=~ or!=~, enter aRE2regular expression into theValue field and clickOk.For example, the regular expressionus-central1-.* matches allus-central1 zones.

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

     You can't use regular expressions to filter theproject_idresource label.

     For example, to view only the time series from one of theus-central1 zones, apply azone=~"us-central1.*" filter.

When you add multiple filters, the following points apply:

• You can use the same label multiple times, which lets youspecify a filter for a range of values.

• All filter criteria must be met; they constitute a logicalAND.

To edit the value or comparator for a filter,on the filter element, clickarrow_drop_downMenu, make yourchanges, and then clickOk.

To delete a filter, clickcancelCancel.

Write PromQL queries

To enter a PromQL query, do the following:

1. In the Google Cloud console, go to theleaderboard Metrics explorer page:

   Go toMetrics explorer

   If you use the search bar to find this page, then select the result whose subheading isMonitoring.

2. In the toolbar of the Google Cloud console,select your Google Cloud project. ForApp Hubconfigurations, select the App Hub host project or management project.
3. In the toolbar of thequery-builder pane, select the button whose name is eithercode MQL orcode PromQL.
4. Verify thatPromQL is selectedin theLanguage toggle. The language toggle is in the same toolbar thatlets you format your query.
5. Optional: Disable theAuto-run toggle.

6. Enter your query into the query editor. For example, to chart the averageCPU utilization of the VM instances in your Google Cloud project, use thefollowing query:

   avg(compute_googleapis_com:instance_cpu_utilization)

   For more information about using PromQL,seePromQL in Cloud Monitoring.

7. ClickRun query.

   When theAuto-run toggle is enabled,theRun query button isn't shown.

Write Monitoring-filter queries

When you want to do any of the following, you must usedirect filter mode,which lets you enter aMonitoring filter:

• Display a service-level objective (SLO).
• Display the count of processes running on virtual machines (VMs).
• Display a custom metric for which you don't yet have data.
• Filter a time series based on a label for which you don't yet have data.

AMonitoring filter, or equivalently ametric filter, is an expression that Monitoringuses to identify the time series to chart.For example, the following expression resultsin a chart displaying a count of processes whose name includesnginx:

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

You can also use Monitoring filters to identify time seriesby their resource and metric type. The following expression results in achart displaying the count of log entries for all Google Cloud virtualmachine instances in theus-east1-b zone:

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:

1. In the Google Cloud console, go to theleaderboard Metrics explorer page:

   Go toMetrics explorer

   If you use the search bar to find this page, then select the result whose subheading isMonitoring.

2. In the toolbar of the Google Cloud console,select your Google Cloud project. ForApp Hubconfigurations, select the App Hub host project or management project.

3. Clickhelp_outlineHelp on theMetric element, and thenselectDirect Filter Mode.

   TheMetric andFilter elements are deleted, and aFilterselement lets you enter text, is created.

   If you selected a resource type, metric,or filters before switching toDirect Filter Mode mode, thenthose settings are shown in theFilters element.

4. In the text area of theFilters element, entera Monitoring filter expression.For syntax information, see the following documents:

   • Monitoring filters
   • Process-health filters
   • Retrieving SLO data

   When you use direct filter mode and no data is available that satisfies thefilter, an error is shown. Common error messages includeChart definition invalid andNo data is available for the selected timeframe.

5. Optional: Configure how the time series are grouped and aligned. For moreinformation, seeChoose how to display charted data.

To return to the menu-driven interface,clicktuneExit direct filter mode.

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

• For information on view options, seeSet chart display options.
• For more information about interacting with the chart itself, seeExplore charted data.

The contents of this section doesn't apply when you've selected the datato chart by using PromQL.

Combine time series

You can reduce the amount of data returned for a metric by combiningdifferent time series. To combine multiple time series, you typicallyspecify one or more labels and a function. Time series that have thesame value for all specified labels are grouped, and then the functionthat you specified combines those time series into a new time series.

The settings in theAggregation element can change the number oftime series that your chart displays. The default settings for the this elementare determined by the metric type you selected.To modify the display, do any of the following:

• To display every time series, in theAggregation element,ensure the first menu is set toUnaggregated and the second menu isset toNone.

• To combine time series, in theAggregation element,do the following:

  1. Expand the first menu and select a function.

     The chart is refreshed and displays a single time series. For example,if you selectMean, then the displayed time series is the averageof all time series.

     The function menu supports common algebraic functions, like mean, minimum,maximum, and sum. TheCount time series option counts the number oftime series that match the metric and filter settings. Thepercentile options, like99th percentile, are statistical valuesderived from the time series that match the metric and filter settings.

  2. To combine time series that have the same label values,expand the second menu, and then select one or more labels.

     The chart is refreshed and shows one time series for each uniquecombination of label values. For example, to display on time seriesper zone, set the second menu tozone.

• To configure the spacing between data points, clickaddAdd query element, selectMin Interval,and then enter a value.

For example, if you set the function toSum and select the labeluser_labels.version, then there is one time series foreach value of the labeluser_labels.version.The data points in each time series are computed from the sum of all the valuesfor individual time series for a specific version:

When you select multiple labels, time series that have the samevalues for the selected labels are combined.The resulting chart displays one time series for each combination of labelvalues. The order in which you specify the labels doesn't matter.The following screenshot shows a chart where time series are combined by theuser_labels.version andsystem_labels.machine_image labels:

As shown, the chart displays one time series for each pair of label values.The fact that you get a time series for each combination of labels means thatthis technique can create more data than you can usefully put on asingle chart.

Show all time series

To show all time series, on theAggregation element,set the first menu toUnaggregated and the second menu toNone.

Align time series

Alignment is the process of converting the time series data received byMonitoring into a new time series which has data points atfixed intervals. The process of alignment consists of collecting all datapoints received in a fixed length of time, applying a function to combinethose data points, and assigning a timestamp to the result. Thatfunction might compute the average of all samples orit might extract the maximum of all samples.

Set alignment interval

To specify the fixed length of time for points to be combined,clickaddAdd query element in the query pane,selectMin Interval, and then complete the dialog.

For example, consider a metric with a sampling period of one minute. If a chartis configured to display 1 hour of data, then the chart can display all 60 datapoints. If theMin Interval field is set to10 minutes, then thechart displays 6 data points. However, if you now configure the chart to displayone week of data, then there are too many points to display in the chart so thethe interval over which points are combined is automatically modified.In this example, the modified interval is one hour.

The following screenshot illustrates the CPU utilization of theCompute Engine VM instances in a particular Google Cloud project.In this image, theMin Interval field is set to1 minute:

For comparison, the following screenshot illustrates the effect of changingthe interval from1 minute to5 minutes:

By increasing the period, the resulting chart has fewer points, decreasing from60 points per time series to 10 points per time series. By increasing theMin Interval field, more points are combined, which has a smoothingeffect on the plotted data.

Set alignment function

When you select the function for aggregation, Cloud Monitoring selectsthe alignment function for you. Cloud Monitoring determines the optimalalignment function based on the metric type you selected and your choicefor the aggregation function. However, you can specify an alignment functionand override the choice made by Cloud Monitoring.

To specify the alignment function,do the following:

1. In theAggregation element, expand the first menu and selectConfigure aligner. TheAlignment function andGrouping elements are added.
2. Expand theAlignment function element and make a selection.

While most of the supported alignment functions perform commonmathematical functions, some perform more complicated actions:

• next older: To retain only the most recent sample within an alignmentperiod, selectnext older. This function is commonly used withuptime checks and is a good choice when you only care about the most recentvalue.

  This function is valid only for gauge metrics.

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

  This function is valid only for gauge and delta metrics when theyhave a distribution data type.

• delta: To convert a cumulative metric or a delta metric into a deltametric with one sample per alignment period, use this function.Data interpolation might occur when you use this function.For an example, seeKinds, types, and conversions.

  This function is valid only for cumulative and delta metrics.

• rate: To convert a cumulative or delta metric into a gauge metric, usethis function. If you choose this function, you can think of the time seriesbeing transformed as it was with a delta function and then divided bythe alignment period. For example, if the unit of the original time seriesis MiB and the unit of the alignment period is second, then thechart has a unit of MiB per second. For more information, seeKinds, types, and conversions.

  This function is valid only for cumulative and delta metrics.

For more information on the available alignment functions,seeAlignerin the API reference.

Secondary grouping and alignment

When you have multiple time series that already represent aggregations,you can reduce all the time series on the chart to a singletime series by choosing aSecondary Aggregator. For example, if yougroup data by zone, your chart shows one time series for each zone. Tocreate a chart with a single time series, use the secondary aggregationfields.

For some metric types, you have the option to transform the data. If thisoption is available and if you set theTransform field to a value otherthanNone, all other fields are the secondary aggregation settings.

When the secondary aggregation fields are configurable, to access those fields,to the following:

1. ClickaddAdd query element,and then selectSecondary aggregation.
2. Configure theSecondary aggregation element.

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

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

Configure the name of a legend column

TheLegend Alias field lets you customize a description for thetime series on your chart. These descriptions appear on the tooltip forthe chart and on the chart legend in theName column.By default, the descriptions in the legend are created for you from the valuesof different labels in your time series. Because the system selects thelabels, the results might not be helpful to you. To build a template fordescriptions, use this field.

You can enter plain text and templates in theLegend Alias field. Whenyou add a template, you add an expression that is evaluated when the legendis displayed.

To add a legend template to a chart, do the following:

1. In theDisplay pane,expandexpand_moreLegend Alias.
2. ClickaddDisplay template variable suggestionsand select an entry from the menu.For example, if you selectzone, then thetemplate${resource.labels.zone} is added.

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

In the chart legend, the values generated from the template appear in a columnwith the headerName and in the tooltip:

You can configure the legend template to include multiple text strings andtemplates; however, the display space available on the tooltip is limited.

What's next

• Explore charted data
• User-defined metrics overview
• Configure the legend template
• Set chart display options