Add charts and tables to a custom dashboard

This document describes how to add charts, indicators, and tables to a custom dashboard by using the Google Cloud console. You can display metric data over a time interval by adding a line chart, a stacked-area chart, a bar-chart, or a heatmap chart. If you are only interested in the most recent measurements, then add a table or an indicator. Indicators change color based on how the data compares to warning and danger thresholds. The visualizations you can add to dashboards—including charts, indicators, and tables—are collectively called widgets. For general information about the different widget types, see Dashboards overview.

Charts, tables, and indicators on custom dashboards can display any metric type that has a numeric or distribution value, including user-defined metrics and log-based metrics. Charts can't graph string-type data.

This document describes how to add charts, indicators, and tables to a custom dashboard. See the following documents for information about adding other types of widgets to your dashboards:

• Alerting policies and incidents
• Log entries
• Descriptive text
• Service-level objectives (SLOs) for a set of services

For information about the Cloud Monitoring API, see Manage dashboards by API.

Before you begin

• To get the permissions that you need to create and modify custom dashboards by using the Google Cloud console, ask your administrator to grant you the Monitoring Editor (roles/monitoring.editor) IAM role on your project. For more information about granting roles, see Manage access.

  You might also be able to get the required permissions through custom roles or other predefined roles.

  For more information about roles, see Control access with Identity and Access Management.

• You can put up to 40 widgets on a dashboard.

Add charts and tables to a dashboard

This section describes how to configure charts and tables by using the Google Cloud console:

• Charts show data over time and there are four styles available: Line, Stacked area, Stacked bar, and Heatmap. After a chart is configured, you can change its widget type. For information about why you might select a specific style, see Charts that show data over time.

  For information about using the Cloud Monitoring API to configure a chart, see Dashboard with an XyChart widget.

• Tables contain one row for each monitored time series and they only show the most recent value. There are two styles of tables. The Table widget displays a numeric value like "25%". The Top List widget displays both the value and a visual indicator of the value compared to the range of possible values. You can change between these widget types. For more information and an example, see Display data in tabular form on a dashboard.

  For information about using the Cloud Monitoring API to configure a table, see Dashboard with a TimeSeriesTable widget.

To add a chart or a table to a dashboard, do the following:

1. In the Google Cloud console, select Monitoring or click the following button:
   Go to Monitoring
2. In the navigation pane, select Dashboards, then select the dashboard that you want to view or edit.
3. If the Edit dashboard button is shown, then click it.

4. Select a chart or table widget from the Chart library, or drag one of these widgets from the library to the graph area.

5. Specify the data shown by the widget:

   • To quickly configure the widget, use Basic mode. This mode provides minimal configuration options. You can always switch from a basic configuration to a different configuration mode.
   • To have access to all configurable fields or to enter a Monitoring filter, use Advanced mode. You might not be able to switch to a different configuration mode.
   • To use the Monitoring Query Language (MQL), select the MQL tab. When you use MQL, you can't switch to a different configuration mode and retain your query.

   The following table describes the options for each mode:

Basic

To configure the widget, complete the following steps:

1. Select the time series data that you want to view.
2. (Optional) Group time series.
3. (Optional) Configure the chart view options.
4. (Optional) Chart multiple metric types.

Select the time series data that you want to view

To select the time series to chart, do one of the following:

• To display a metric type, such as the CPU utilization of a VM, use the menus to make your selections:

  1. Click Select a metric and then use the menus to select a resource type and a metric type.

     To reduce the number of menu options, enter the name of a resource or a metric type in the Filter bar. For example, to chart the CPU utilization of a VM instance, you might enter utilization in the filter bar.

     To list all resource and metric types, set the Show only active resources & metrics toggle to disabled. By default, this toggle is set to enabled so only metrics and resources with data are shown in the menus.

  2. (Optional) To specify a subset of data to display, add a filter or apply template variables. For example, you can view data for one zone by applying a filter. You can add multiple filters. For more information about filters, see Filter charted data. For information about template variables, see Filter a dashboard.

     To add a filter, click Add a filter and then select the label and label's value. For example, to show time series only for the us-east1-b zone, enter the filter zone = us-east1-b.

     To apply a template variable, use the menu.

• To display a service level objective or the count of processes running on VMs, enter a Monitoring filter:

  1. Click Help on the Select a metric menu.
  2. Select Direct filter mode.
  3. Enter the Monitoring filter in the text box.

For more information about these choices, see Select metrics for charts on dashboards.

Group time series

1. Determine if you want to view every time series or if you want to group time series by label values.

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

   This option isn't available for heatmap charts, as these charts can only display a single time series.

2. To specify how to combine data points within a time series, use the radio buttons.

   For example, if a chart can display 60 data points and data is written at 1 point per minute, then the chart can display 1 hour of data. To display 3 hours of data, you have to reduce 180 data points to 60. When this selector is mean, then each point on the chart is the average of three points in the original time series.

Configure the chart view options

These fields aren't available for tables.

• (Optional) To change the Y-axis from the right axis to the left axis, click Y-axis and select Left.

  When you configure a chart to display multiple metric types, ensure that the metric types are mapped to the same Y-axis have the same units. For more information, see Chart with multiple metrics displays an error message.

  This option isn't available for heatmap charts.

• (Optional) To configure how the data is displayed in a chart, click Settings:

  • Add a reference line
  • Set x-ray, color, or statistics mode
  • Show outliers
  • Compare current to past data
  • Set the Y-axis to log scale
  • Configure legends.

(Optional) Chart multiple metric types

This option isn't available for tables.

To display another metric type on your chart, click Add another metric and then repeat the previous steps. A chart can display a maximum of 10 metric types.

The first time you click Add another metric, the selections that you previously made are shown in the Time series A pane. Also, the Time series B pane opens. This pane contains the configuration fields that you complete to chart the second metric type.

The following screenshot illustrates this behavior:

Advanced

To configure the widget, complete the following steps:

1. Select the time series data that you want to view.
2. Select how the time series are preprocessed.
3. (Optional) Group time series.
4. (Optional) Configure the chart view options.
5. (Optional) Chart multiple metric types.
6. (Optional) Chart a ratio of metric types.

Select the time series data that you want to view

To select the time series to chart, do one of the following:

• To display a metric type, such as the CPU utilization of a VM, use the menus to make your selections:

  1. Click Select a metric and then use the menus to select a resource type and a metric type.

     To reduce the number of menu options, enter the name of a resource or a metric type in the Filter bar. For example, to chart the CPU utilization of a VM instance, you might enter utilization in the filter bar.

     To list all resource and metric types, set the Show only active resources & metrics toggle to disabled. By default, this toggle is set to enabled so only metrics and resources with data are shown in the menus.

  2. (Optional) To specify a subset of data to display, add a filter or apply template variables. For example, you can view data for one zone by applying a filter. You can add multiple filters. For more information about filters, see Filter charted data. For information about template variables, see Filter a dashboard.

     To add a filter, click Add a filter and then select the label and label's value. For example, to show time series only for the us-east1-b zone, enter the filter zone = us-east1-b.

     To apply a template variable, use the menu.

• To display a service level objective or the count of processes running on VMs, enter a Monitoring filter:

  1. Click Help on the Select a metric menu.
  2. Select Direct filter mode.
  3. Enter the Monitoring filter in the text box.

For more information about these choices, see Select metrics for charts on dashboards.

Select how the time series are preprocessed

In general, this setting can be left at the default value.

Preprocessing options are displayed when the selected metric is a delta or cumulative metric kind. The metric's value type determines the specific options that are available.

Note: When you've selected a metric with a distribution value type and the widget type is a heatmap chart, leave the option set to No preprocessing step. Any other choice results in an invalid combination. For more information, see [Distribution metrics][cc-chart-distr].

When preprocessing options are available, you use the radio buttons to specify how you want the raw data processed before the data is aligned. The following example shows the options when time series for a DELTA metric are selected:

For DELTA metrics, when Rate is selected, the data values are divided by the sampling rate. When No preprocessing step is selected, the sampling rate doesn't scale the data values. For example, when the units for the metric are MiB, then selecting rate changes the units change to MiB per second. For more information and an example, see Kinds, types, and conversions.

Group time series

1. Select the alignment parameters. In general, these fields can be left at the default values. For more information, see Alignment: within-series regularization.

2. Determine if you want to view every time series or if you want to group time series by label values.

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

     When you are displaying time series on a heat map, you must combine the time series by using this approach. Heatmaps can only display a single time series. For more information, see Distribution metrics.

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

     • Ensure the Group by field is empty and select none for the Group by function.
     • Expand the Group by menu, select Add all, and then select from the Group by function menu.

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

   For general information about the alignment and grouping, see Choosing how to display the data.

Configure the chart view options

These fields aren't available for tables.

• (Optional) To change the Y-axis from the right axis to the left axis, click Y-axis and select Left.

  When you configure a chart to display multiple metric types, ensure that the metric types are mapped to the same Y-axis have the same units. For more information, see Chart with multiple metrics displays an error message.

  This option isn't available for heatmap charts.

• (Optional) To configure how the data is displayed in a chart, click Settings:

  • Add a reference line
  • Set x-ray, color, or statistics mode
  • Show outliers
  • Compare current to past data
  • Set the Y-axis to log scale
  • Configure legends.

(Optional) Chart multiple metric types

This option isn't available for tables.

To display another metric type on your chart, click Add another metric and then repeat the previous steps. A chart can display a maximum of 10 metric types.

The first time you click Add another metric, the selections that you previously made are shown in the Time series A pane. Also, the Time series B pane opens. This pane contains the configuration fields that you complete to chart the second metric type.

The following screenshot illustrates this behavior:

(Optional) Chart a ratio of metric types

This option isn't available for tables.

When you are interested in, for example, the rate of errors instead of the absolute number of errors, you need to chart a ratio of metric types. A chart that displays a ratio of metric types might show anomalies due to sampling and alignment differences. For references to examples and more information, see Ratios of metrics.

The following steps assume that you have completed the steps to chart a metric type. In the following steps, you select a second metric type and then convert the chart to show a ratio:

1. Select Add another metric.

   When you click Add another metric, the selections that you previously made are shown in the Time series A pane. Also, the Time series B pane opens.

2. Select the metric type for Time series B.

   Both metric types must have the same metric kind. For example, if Time Series-A is a GAUGE metric, then select a metric type that has a GAUGE metric kind.

3. Ensure that the value of the Minimum alignment period field is the same for both metric types.

4. Set the grouping parameters for the second metric type.

   We recommend that the grouping fields for the second metric type match the values for Time Series-A. For example, you might group both metric types by the zone label.

   You aren't required to use the same grouping for the numerator and denominator; however, you can only group by labels that are common to both fields.

5. Enable Display metrics as ratio.

   When you make this selection, the label Time Series-A is renamed Numerator, and the label Time Series-B is renamed Denominator

6. (Optional) To change which metric type is the numerator, click Swap numerator.

7. (Optional) Expand Show ratio options to configure the secondary aggregation options.

MQL

To add a chart or table to a dashboard by using MQL mode, enter a MQL query.

For example, the following query displays the average CPU utilization of every Compute Engine virtual machine (VM) instance:

fetch gce_instance
| metric 'compute.googleapis.com/instance/cpu/utilization'
| group_by 1m, [value_utilization_mean: mean(value.utilization)]
| every 1m

When you select a heatmap widget, ensure that the aggregation options combine the time series into a single time series. If a heatmap chart displays Your MQL Query has too many time series, then modify the aggregation settings to combine the time series.

For information about computing ratios with MQL, see Computing ratios.

For more information about using MQL, see Introduction to MQL.

For information about adding template filters when using MQL, see Dashboard filters.

PromQL

To add a chart or table to a dashboard by using PromQL mode, enter a PromQL query.

For example, the following query displays the average CPU utilization of your Compute Engine virtual machine (VM) instance:

avg(compute_googleapis_com:instance_cpu_utilization)

When you select a heatmap widget, ensure that the aggregation options combine the time series into a single time series. If a heatmap chart displays Your Query has too many time series, then modify your query to combine the time series.

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

Page-level filters on your custom dashboards are not supported by any PromQL charts on those dashboards.

Add indicators to a dashboard

To view the most recent measurement as compared to a color-coded set of thresholds, add a gauge or a scorecard. Gauges display only the most recent measurement while scorecards also show a history of recent measurements. The background color of these widgets is also color-coded. When the most recent value is within expected ranges, the widget color is white. When the value is in a warning range, the widget becomes amber. Similarly, when the value is in a danger range, the widget becomes red.

Both widgets display a single time series. The following screenshot shows an example of a gauge when the most recent measurement is less than the warning and danger thresholds:

The remainder of the information in this section is for the Google Cloud console. For information about using the Cloud Monitoring API, see Dashboard with a basic Scorecard.

To add a gauge or scorecard to a dashboard, do the following:

1. In the Google Cloud console, select Monitoring or click the following button:
   Go to Monitoring
2. In the navigation pane, select Dashboards, then select the dashboard that you want to view or edit.
3. If the Edit dashboard button is shown, then click it.
4. Select a gauge or scorecard widget from the Chart library, or drag one of these widgets from the library to the graph area.
5. Specify the data shown by the widget:
   • To quickly configure the widget, use Basic mode. This mode provides minimal configuration options. You can always switch from a basic configuration to a different configuration mode.
   • To have access to all configurable fields or to enter a Monitoring filter, use Advanced mode. You might not be able to switch to a different configuration mode.
   • To use the Monitoring Query Language (MQL), select the MQL tab. When you use MQL, you can't switch to a different configuration mode and retain your query.

   The following table describes the options for each mode:

Basic

To configure the widget, complete the following steps:

1. Select the time series data that you want to view.
2. Combine the time series into a single time series.
3. Configure the warning and threshold levels.

Select the time series data that you want to view

To select the time series to chart, do one of the following:

• To display a metric type, such as the CPU utilization of a VM, use the menus to make your selections:

  1. Click Select a metric and then use the menus to select a resource type and a metric type.

     To reduce the number of menu options, enter the name of a resource or a metric type in the Filter bar. For example, to chart the CPU utilization of a VM instance, you might enter utilization in the filter bar.

     To list all resource and metric types, set the Show only active resources & metrics toggle to disabled. By default, this toggle is set to enabled so only metrics and resources with data are shown in the menus.

  2. (Optional) To specify a subset of data to display, add a filter or apply template variables. For example, you can view data for one zone by applying a filter. You can add multiple filters. For more information about filters, see Filter charted data. For information about template variables, see Filter a dashboard.

     To add a filter, click Add a filter and then select the label and label's value. For example, to show time series only for the us-east1-b zone, enter the filter zone = us-east1-b.

     To apply a template variable, use the menu.

• To display a service level objective or the count of processes running on VMs, enter a Monitoring filter:

  1. Click Help on the Select a metric menu.
  2. Select Direct filter mode.
  3. Enter the Monitoring filter in the text box.

For more information about these choices, see Select metrics for charts on dashboards.

Combine the time series into a single time series

You use the radio buttons to specify how the data from different time series are combined. For example, to average the time series, select mean.

Configure the warning and threshold levels

Do one of the following:

• For gauges, do the following:

  1. Enter the Minimum and Maximum values for the metric. When the gauge displays a percentage, set these values to 0 and 1 respectively.

  2. Configure the warning and danger thresholds.

     For example, the following screenshot illustrates a configuration for a gauge with the Warning above and Danger above thresholds are set:

     

• For scorecards, do the following:

  1. Set the Spark chart view. The view determine how the past data is shown. For example, if you select Line, then a line is shown.
  2. Configure the warning and danger thresholds.

Advanced

To configure the widget, complete the following steps:

1. Select the time series data that you want to view.
2. Combine the time series into a single time series.
3. Configure the warning and threshold levels.

Select the time series data that you want to view

To select the time series to chart, do one of the following:

• To display a metric type, such as the CPU utilization of a VM, use the menus to make your selections:

  1. Click Select a metric and then use the menus to select a resource type and a metric type.

     To reduce the number of menu options, enter the name of a resource or a metric type in the Filter bar. For example, to chart the CPU utilization of a VM instance, you might enter utilization in the filter bar.

     To list all resource and metric types, set the Show only active resources & metrics toggle to disabled. By default, this toggle is set to enabled so only metrics and resources with data are shown in the menus.

  2. (Optional) To specify a subset of data to display, add a filter or apply template variables. For example, you can view data for one zone by applying a filter. You can add multiple filters. For more information about filters, see Filter charted data. For information about template variables, see Filter a dashboard.

     To add a filter, click Add a filter and then select the label and label's value. For example, to show time series only for the us-east1-b zone, enter the filter zone = us-east1-b.

     To apply a template variable, use the menu.

• To display a service level objective or the count of processes running on VMs, enter a Monitoring filter:

  1. Click Help on the Select a metric menu.
  2. Select Direct filter mode.
  3. Enter the Monitoring filter in the text box.

For more information about these choices, see Select metrics for charts on dashboards.

Combine the time series into a single time series

1. Select the alignment parameters. In general, the alignment parameters can be left at the default values. For more information, see Alignment: within-series regularization.

2. Select the group by function. This function combines the time series together.

Configure the warning and threshold levels

Do one of the following:

• For gauges, do the following:

  1. Enter the Minimum and Maximum values for the metric. When the gauge displays a percentage, set these values to 0 and 1 respectively.

  2. Configure the warning and danger thresholds.

     For example, the following screenshot illustrates a configuration for a gauge with the Warning above and Danger above thresholds are set:

     

• For scorecards, do the following:

  1. Set the Spark chart view. The view determine how the past data is shown. For example, if you select Line, then a line is shown.
  2. Configure the warning and danger thresholds.

MQL

To configure the widget, enter a MQL query that combines the time series into a single time series.

For example, consider the query for the CPU utilization of a VM instance. This query groups the data by zone and then averages the data in each zone:

fetch gce_instance
 | metric 'compute.googleapis.com/instance/cpu/utilization'
 | group_by [zone], mean(val())

When all your VM instances are in the same zone, a gauge or scorecard can display the requested data. However, when your VM instances are in multiple zones, these widgets display the error message Your MQL Query has too many time series.

To resolve this error condition, ensure that the last group_by clause combines the time series:

fetch gce_instance
 | metric 'compute.googleapis.com/instance/cpu/utilization'
 | group_by [zone], mean(val())
 | every 1m
 | group_by [], max(val())

In the last group_by clause, the first argument, [], specifies that the time series are to be combined and the second argument, max(val()), defines how the time series are to be combined. After the grouping operation completes, there is a single time series.

For more information about using MQL, see Introduction to MQL.

PromQL

To configure the widget, enter a PromQL query that combines the time series into a single time series.

For example, consider the query for the CPU utilization of a VM instance. If you have multiple VMs, this query retrieves multiple time series and can't be displayed by a gauge or scorecard:

compute_googleapis_com:instance_cpu_utilization

If your query returns multiple time series, a gauge or scorecard widget gives you the error message Your Query has too many time series.

To resolve this error condition, ensure that query returns a single time series. For example, the following query computes the average across all time series:

avg(compute_googleapis_com:instance_cpu_utilization)

For more information about using MQL, see PromQL in Cloud Monitoring.

Display data in tabular form on a dashboard

To view the most recent data in tabular form, add a table. Tables can display any metric type that has a numeric value, and they can display percentiles for distribution-valued metrics. Tables only show the most recent value, similar to the behavior of gauges and scorecards. However, unlike gauges and scorecards, tables contain one row for each monitored time series.

There are two styles of tables. The Top List widget is preconfigured to have two columns and to limit the number of rows. One column in the Top List widget displays a label like instance_id and the other displays both the value and a visual indicator of the value compared to the range of possible values. The Table widget is preconfigured to display one column for each label with more than one unique value, one row for each time series, and a numeric value like "25%".

Both widgets are represented by the same data structure. Therefore, after you add one of these widgets to your dashboard, you can limit the number of rows shown, change the columns displayed by the table, and change how the value is represented.

The following screenshot illustrates a dashboard that displays the CPU utilization of virtual machine instances by using a Top List widget and a Table widget:

For information about how to add tables to a dashboard, see the following documents:

• To use the Google Cloud console, see the section titled Add charts and tables in this document.
• To use the Cloud Monitoring API, see Dashboard with a TimeSeriesTable widget.

Sort and filter tables

You can change the order of the rows in the table display, and you can filter the table contents so that only specific rows are shown. These settings aren't persistent. When you leave the dashboard page or when you reload the dashboard, the sorting and filtering options you applied are discarded.

You have the following sorting and filtering options:

• To sort the table by a column, click the column header.

• To change the table columns, click View columns, make your modifications, and then click OK.

• To list only specific rows, add one or more filters. You can add multiple filters. When you don't specify the OR operator between two filters, a logical-AND joins those filters.

  To add a filter, click Enter property name or value, select a property from the menu, and then enter a value or select from the value menu. For example, if you filter on the property Name and enter the value demo, then the table lists only rows where the Name field includes the value demo.

What's next

You can also add the following widgets to your custom dashboards:

• Alert charts and incidents
• Log entries
• Descriptive text
• Service-level objectives (SLOs) for a set of services

For information about exploring charted data and filtering your dashboards, see the following documents:

• Explore charted data
• Filter a custom dashboard