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 that display time-series data. For information about adding other types of widgets to your dashboards, see the following documents:

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 to projects, folders, and organizations.

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. A single chart can display multiple metric types. For example, you might configure a chart to display the disk bytes read from your instances and the disk bytes written to your instances.

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 combination of label values. When tables display data from multiple metric types, each row contains a result from all queries, when such a merge is possible.

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 the style between tables and charts, configure table column names, and add thresholds which change the color of the table cells. 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, go to the Dashboards page:
Go to Dashboards

If you use the search bar to find this page, then select the result whose subheading is Monitoring.
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 Metric element, expand the Select a metric menu.
    
    The Select a metric menu contains features that help you find the metric types available:
    
    To find a specific metric type, use the Filter bar. For example, if you by enter util, then you restrict the menu to show entries that include util. Entries are shown when they pass a case-insensitive "contains" test.
    
    To show all metric types, even those without data, click Active. By default, the menus only show metric types with data.
    
    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.
  2. Optional: To specify a subset of data to display, in the Filter element, select Add filter, and then 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. Combine and align time series:
  - To display every time series, in the Aggregation element, set the first menu to Unaggregated and the second menu to None.
  - To combine time series, in the Aggregation element, do the following:
    
    Expand the first menu and select a function.
    
    The chart is refreshed and displays a single time series. For example, if you select Mean, then the displayed time series is the average of all time series.
    
    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 unique combination of label values. For example, to display on time series per zone, set the second menu to zone.
    
    When the second menu is set to None, the chart displays one time series.
  - Optional: To configure the spacing between data points, click Add query element, select Min Interval, and then enter a value.
  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, use the Sort & Limit element.
MQL
1. In the toolbar of the query-builder pane, select the button whose name is either MQL or PromQL.
2. Verify that MQL is selected 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 query-builder pane, select the button whose name is either MQL or PromQL.
2. Verify that PromQL is selected 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 Metric element, click Help, and then select Direct Filter Mode.
  
  The Metric and Filter elements are deleted, and a Filters element that lets you enter text, is created.
  
  If you selected a resource type, metric, or filters before switching to Direct Filter Mode mode, then those settings are shown in the field of the Filters element.
2. Enter a Monitoring filter in the field of the Filters element.
3. Combine and align time series:
  - To display every time series, in the Aggregation element, set the first menu to Unaggregated and the second menu to None.
  - To combine time series, in the Aggregation element, do the following:
    
    Expand the first menu and select a function.
    
    The chart is refreshed and displays a single time series. For example, if you select Mean, then the displayed time series is the average of all time series.
    
    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 unique combination of label values. For example, to display on time series per zone, set the second menu to zone.
    
    When the second menu is set to None, the chart displays one time series.
  - Optional: To configure the spacing between data points, click Add query element, select Min Interval, and then enter a value.
  For more information about grouping and alignment, see Choose how to display charted data.
Optional: Configure the chart or table to display multiple metric types.

Note: When you add multiple metric types and select a table widget, the Google Cloud console displays the values for both metric types on the same row, when possible. For more information, see How tables merge data from multiple metric types.
Menu-driven interface
1. Select Add query. A new query is added. For example, a query with the label B might be added.
2. For the new query, in the Metric element, select a resource type and metric type. You can also add filters, combine time series, and sort and limit the number of displayed time series.
The following screenshot illustrates the Metrics Explorer display when there are two metric types charted:
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 that have the same metric kind. For example, both are GAUGE metrics.
2. Ensure that the value of the Min Interval field is the same for both metric types. To access this field, click Add query element and select Min Interval.
3. Update the aggregation fields.
  
  We recommend that the labels for the denominator metric type match the values set for the numerator metric type. For example, you might select the zone label for the numerator and denominator.
  
  You aren't required to use the same set of labels for both metric types; however, you can only select 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:
5. Optional: To switch the numerator and denominator metrics, in the Ratio element, expand the menu, and then make a selection.
MQL
1. In the toolbar of the query-builder pane, select the button whose name is either MQL or PromQL.
2. Verify that MQL is selected 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 query-builder pane, select the button whose name is either MQL or PromQL.
2. Verify that PromQL is selected 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 a chart or table displays the selected data, use the options in the Display pane:
- Chart options:
  - Analysis mode menu: Select between line charts, x-ray, and statics.
  - Compare to Past menu: Overlay current data with past data.
  - Threshold Line menu: add a reference threshold.
  - Legend Alias menu: configure the name of a legend column.
  - Y-axis assignment, Y-axis labels, and Y-axis scale menus: Configure configure Y-axis assignment, labels, or scale.
- Table options:
  - Value option menu: Select between the latest value and an aggregated value.
  - Visible columns menu: Select which columns are shown.
  - Column formatting menu: Configure column names, alignment of data in a column, units, and whether cells are color-coded.
  - Metric view menu: Select whether the value is show by itself or shown relative to a range of values.
  - Legend Alias menu: configure the name of a legend column.
To apply your changes to the dashboard, in the toolbar, click Apply. To discard your changes, click Cancel.
To save your modified dashboard, in the toolbar, click Save.

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 numeric data. For example, they can display one or more metric type, or percentiles for distribution-valued metrics.

When a table displays one metric type, each row in the table corresponds to one time series. One table column that displays a numeric value, which is either the latest value or an aggregate value. The other columns display the labels in the time series. When a table displays multiple metric types, the data for both metric types is shown on the same row, when possible. For more information, see How tables merge multiple metric types.

There are two widgets that display data in tabular form: Top List widget and Table widget. The primary difference between these two widgets is that the Top List widget sorts the order of the rows and it displays the value along with a visual indicator of the value compared to the range of possible values. Because the Top List widget provides a visual representation of the value, you can't color-code the cell based on how the value compares to a threshold.

For information about configuring tables, see the following sections:

For general information about selecting metrics and setting aggregation options, see the Add charts and tables section 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.
For configuration options, see the following sections of this document:
For information about sorting and filtering your table, see the Sort and filter tables section of this document.
For information about using the API to configure a table, see Dashboard with a TimeSeriesTable widget.

The following screenshot illustrates two tables. The first table displays two metric types, the number of bytes read from instances and the number of bytes written to instances. An aggregated value is shown along with a reference bar. The second table shows the latest value of one metric type, and the value column has been configured to color-code the cell based on how the value compares to a threshold:

Example of table displaying two metric types.

Display latest value or aggregated value

By default, tables display the most recent value. However, a table can show a value that is computed over the time-range selected for your dashboard.

To select between the latest value and the aggregated value, use the Value option field.

If you display the aggregated value, then for each time series, the data within the time range selected by your dashboard is combined by the alignment function. The alignment function is one of the aggregation options and isn't shown by default. To view the alignment function, expand the Aggregation element and in the first element, select Configure aligner. After you make this selection, the Aggregation element is replaced by a Grouping element and a menu named Alignment function.

Select the columns to display

By default, one column in the table displays a numeric value. All other columns correspond to a label in the time series. For label-based columns, the column name is derived from the label.

To configure the columns shown by the table, expand the Visible Columns menu and make your selections.

Configure column format

To configure an individual column, in the Columns element, expand the Override column menu, select the column to be modified, and then do any of the following:
- To set the name of column, use the Display name field.
- To set the alignment of the data in the column, use the Left align, Center align, and Right align buttons.
- To color-code the cell based on how the numeric value compares to a threshold, set the warning and danger thresholds.
- If you write PromQL queries, then use the Unit menu to set the units shown with the data. The units are automatically configured when you configure your query by using menu selections.

Display referential value

Tables can display only a value, or they can display a value relative to the range of values. When the range option is selected, the value is shown along with a blue-colored bar, the length of the bar is proportional to the value shown.

To configure whether a referential value is shown, use the Metric view element.

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, go to the Dashboards page:
Go to Dashboards

If you use the search bar to find this page, then select the result whose subheading is Monitoring.
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 Metric element, expand the Select a metric menu.
    
    The Select a metric menu contains features that help you find the metric types available:
    
    To find a specific metric type, use the Filter bar. For example, if you by enter util, then you restrict the menu to show entries that include util. Entries are shown when they pass a case-insensitive "contains" test.
    
    To show all metric types, even those without data, click Active. By default, the menus only show metric types with data.
    
    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.
  2. Optional: To specify a subset of data to display, in the Filter element, select Add filter, and then 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. Combine the time series by using the Aggregation fields:
  - Expand the first menu and select the function that combines the time series.
  - Expand the second menu and ensure that no labels are selected.
MQL
1. In the toolbar of the query-builder pane, select the button whose name is either MQL or PromQL.
2. Verify that MQL is selected 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 query-builder pane, select the button whose name is either MQL or PromQL.
2. Verify that PromQL is selected 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 Metric element, click Help, and then select Direct Filter Mode.
  
  The Metric and Filter elements are deleted, and a Filters element that lets you enter text, is created.
  
  If you selected a resource type, metric, or filters before switching to Direct Filter Mode mode, then those settings are shown in the field of the Filters element.
2. Enter a Monitoring filter.
3. Combine the time series by using the Aggregation fields:
  - Expand the first menu and select the function that combines the time series.
  - Expand the second menu and ensure that no labels are selected.
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 apply your changes to the dashboard, in the toolbar, click Apply. To discard your changes, click Cancel.
To save your modified dashboard, in the toolbar, click Save.

How tables merge data for multiple metric types

If a table queries for multiple metric types, then the Google Cloud console performs a merge operation by examining the labels attached the aggregated data for both metric types. When the labels that are common to both queries let Monitoring determine a unique row identifier, then a single row on the table displays the most recent value for each query. Otherwise, there is one row for each time series.

For example, suppose a table queries two different metric types. Let's call these queries A and B. The following describes how the query results are merged:

If the result of both queries has the same set of labels, then the merge is always successful. Each row contains the latest value for each query. If a query doesn't return a value for a particular combination of labels, then the table cell is empty.

For example, suppose both queries contain a zone label. The table contains one row for each zone reported by query A and query B. However, if query A returns a time series whose zone is us-central1-a but query B doesn't return a time series with this value, then the latest value for query B is shown as an empty cell.
If the labels for the results of one query are a subset of the labels for the results of the other query, then the results are merged.

For example, suppose that results for both queries include labels for location and cluster_name, but that the results for query A also include a label for memory_type. In this situation, each row corresponds to a time series with unique values for the three labels.

On any row, the value shown for query B is the value of the time series that matches the two common labels, location and cluster_name, and the third label is ignored.
If the results of the two queries don't share any labels or if they share some labels, but not enough to form a unique row identifier, then the results can't be merged. The table lists one row for each time series returned by query A or by query B, and some table cells are empty.

For example, suppose the labels for query A are location and memory_type, and that the labels for query B are location and cluster_name. Even though the label location is common, that label isn't sufficient to create a unique row identifier.

As described in the next section, you might be able to resolve a merge failure.

Resolve merge failure

When you are charting multiple metrics, a merge failure might occur because the metrics use different label names for the same field. One way you can resolve this failure is to convert one query to PromQL and then use the label_replace() function to convert the label names used by one metric type to match those of the other metric type.

For example, consider a table configured with two queries:

A: Queries the Prometheus/kube_pod_container_status_ready/gauge metric type. The aggregation options are set to sum time series after grouping the data by the cluster label.
B: Queries the kubernetes.io/container/memory/request_bytes metric type. The aggregation options are set to sum time series after grouping the data by the cluster_name label.

The table can't merge the results because the results for query A and query B have different labels.

To resolve the failure, convert query A to PromQL and replace cluster with cluster_name. The following example illustrates the modified query:

sum by (cluster_name)(
    label_replace(
        avg_over_time(kube_pod_container_status_ready[${__interval}]),
        "cluster_name", "$1", "cluster", "(.*)"
    )
)

With the changes, both queries produces the same set of labels. Therefore, each row in the table lists a cluster name, the value for query A, and the value for query B.

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

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

Display latest value or aggregated value

Select the columns to display

Configure column format

Display referential value

Sort and filter tables

Display the most recent data with warning or error indication

Menu-driven interface

MQL

PromQL

Monitoring filter

How tables merge data for multiple metric types

Resolve merge failure

What's next