Add charts and tables to a custom dashboard

This document describes how to add charts, tables, gauges, and scorecards 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, a pie chart, a gauge, or a scorecard. Gauges and scorecards change color based on how the most recent value compares to warning and danger thresholds.

The visualizations you can add to dashboards are collectively called widgets. For general information about the different widget types, see Dashboards overview.

Charts, tables, gauges, and scorecards 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, tables, gauges, and scorecards to a custom dashboard. See the following documents for information about adding other types of widgets to your dashboards:

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.
To add a widget to a dashboard, you can either select the visualization and then configure the widget, or you can select the data type first and then configure the visualization.

For example, to add a table that displays the CPU utilization of your VM instances to a dashboard, you can do either of the following:
- Select the Table widget and then configure that widget to display the CPU utilization of your VM instances.
- Select the Metric data type, configure the widget to display the CPU utilization of your VM instances, and then change the widget type to Table.
The instructions on this page assume that you select the data type first, and then configure how that data is displayed.

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:

In the Google Cloud console, select Monitoring, and then select Dashboards, or click the following button:
Go to Dashboards
Do one of the following:
- To create a new dashboard, select Create dashboard.
- To update an existing dashboard, find the dashboard in the list of all dashboards and select its name.
In the toolbar, click Add widget.
In the Add widget dialog, select Metric.
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.
Optional: Configure the chart to display multiple metric types.
Menu-driven interface
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.$
MQL
Not supported.

PromQL
Not supported.

Monitoring filter
Not supported.
Optional: Configure the chart to display a ratio of metric types.
Menu-driven interface
1. Configure the chart to display two metric types.
2. Ensure that the value of the Minimum alignment period field is the same for both metric types. To view the alignment parameters, click More options.
3. 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 types; however, you can only group by labels that are common to both metric types.
4. In the toolbar of the query pane, select Create ratio, 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.$
5. 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.
Optional: To change the visualization, in the Display pane, click Widget type and then make a selection.

The Widget type menu lists all widget types that can display the same type of data; however, some widgets might not be enabled. For example, consider a chart on a dashboard configured to display one metric type. The line chart displays multiple time series, and that each measured value is a double:
- Table, Pie chart, Line chart, Stacked bar chart, and Stacked area chart widgets are listed as Compatible. You can select any of these types.
  
  Note: To display the data in tabular form, set the widget type to Table. If you select Table in the toggle labeled Chart Table Both, then the display is changed, but that setting isn't saved.
- Scorecard and Gauge widgets are listed as Compatible with adjustments because these widgets can display only a single time series. To enable these widget types, modify the grouping configuration.
- The Heatmap widget is disabled because these widgets can only display distribution-valued data.
- The logs panel isn't listed because the logs panel can't display time-series 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.
To save your changes, click Apply. To discard your changes, click Cancel.

Display only the most recent data

Monitoring provides you with several ways to visualize only the most recent measurements, instead of viewing the history of measurements:

To graphically display the most recent value of each time series, where each value is shown as a fraction of the sum of all values, add a pie chart. You can configure these charts to display the total value.
To display the most recent value of each time series in a tabular form, add a table. You can limit the number of rows in a table, and you can configure the rows of a table to show a value as compared to a range of values.
To get a green, amber, or red indication of the most recent value as compared to a set of thresholds, add a gauge or scorecard to the dashboard.

Graph the most recent data with a pie chart

To view the most recent data as a fraction of the total, add a pie chart. Like tables, a pie chart can display any metric type that has a numeric value, and they can display percentiles for distribution-valued metrics. Each time series contributes one slice to the pie.

The following screenshot illustrates a dashboard that displays the CPU utilization of virtual machine instances by using two different configurations of a Pie chart widget:

Example of **PieChart** widgets.

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

Google Cloud console: See the section titled Add charts and tables in this document.
- After you select the data to chart, in the Display pane, set the Widget type field to Pie chart.
- To display the total value, set the Chart type field to Donut.
Cloud Monitoring API: See Dashboard with a PieChart widget.

Display the most recent data in tabular form

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:

Example of **Top List** and **Table** widgets.

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

Google Cloud console: See the section titled Add charts and tables in this document.

After you select the data to chart, in the Display pane, set the Widget type field to Table or to Top List.
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.

Display the most recent data with warning or error indication

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:

Example of a gauge.

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:

In the Google Cloud console, select Monitoring, and then select Dashboards, or click the following button:
Go to Dashboards
Do one of the following:
- To create a new dashboard, select Create dashboard.
- To update an existing dashboard, find the dashboard in the list of all dashboards and select its name.
In the toolbar, click Add widget.
In the Add widget dialog, select Metric.
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 the time series:
  - Leave the Labels menu empty.
  - Optional: Modify the value of the Grouping function.
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. You must ensure that the aggregation fields are set to combine all time series. 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
| group_by [], [value_utilization_mean_mean: mean(value_utilization_mean)
```
  For more information about MQL, see the following documents:
  - Introduction to MQL
  - Using the code editor
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 the time series:
  - Leave the Labels menu empty.
  - Optional: Modify the value of the Grouping function.
In the Display pane, configure the gauge or scorecard:
1. Click Widget type and select Gauge or Scorecard.
2. For gauge widgets, click Gauge range, and then set the minimum and maximum values. When a gauge displays a percentage, set these values to 0 and 1 respectively.
3. Click Gauge threshold, and then set the warning and danger thresholds. Threshold fields that are empty aren't used.
  
  For the gauge displayed previously, two thresholds are set. Values higher than 0.9 are in the danger range. Values higher than 0.7 but not in the danger range, are in the warning range.
4. For scorecards, click Spark chart view, then expand the menu of options, and then select the display style.
To save your changes, click Apply. To discard your changes, click Cancel.

What's next

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

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

Add charts and tables to a custom dashboard

Before you begin

Add charts and tables to a dashboard

Menu-driven interface

MQL

PromQL

Monitoring filter

Menu-driven interface

MQL

PromQL

Monitoring filter

Menu-driven interface

MQL

PromQL

Monitoring filter

Display only the most recent data

Graph the most recent data with a pie chart

Display the most recent data in tabular form

Sort and filter tables

Display the most recent data with warning or error indication

Menu-driven interface

MQL

PromQL

Monitoring filter

What's next