Add dashboard widgets

This document describes how to add widgets to a custom dashboard by using Google Cloud Console. Custom dashboards can display metric data, alerting policies, descriptive text, and log entries. In general, dashboard widgets can display any metric type that has a numeric or distribution value, including custom metrics and logs-based metrics. Dashboard widgets can't graph string-type data.

When you add widgets that display metric data, you can display that data over a time interval or show only the most recent data. For example, to display a metric over a time interval, add a line chart, a stacked-area chart, a bar-chart, or a heatmap chart. To display only the most recent data, add a table or indicator. Indicators change color based on how the data compares to warning and danger thresholds. For general information about the different widget types, see Dashboards and charts.

You can put up to 40 widgets on a dashboard.

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

Before you begin

Before you create or modify a dashboard, ensure that you have one of the following Identity and Access Management roles:

  • roles/monitoring.dashboardEditor
  • roles/monitoring.editor
  • roles/monitoring.admin
  • roles/owner

For more information about roles, see Access control.

Add charts and tables to a dashboard

This section describes how to configure line charts, stacked-area charts, stacked-bar charts, heatmap charts, and tables, by using the Cloud Console. For information about using the Cloud Monitoring API, see Dashboard with an XyChart widget.

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

  1. In the 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 Editing isn't shown, then click Viewing and select Switch to Editing mode.
  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) Configure the chart to display multiple metrics.

Select the time series data that you want to view

  1. Select a metric and resource type, or enter a Monitoring filter.

    • To select a metric and resource type, use the menus. When you select a resource, that applies a filter to the metric menu, so only metrics for that resource are listed. Similarly, when you select a metric, that applies a filter to the resource menu.

      To find a specific entry, enter text into the menu's filter area, or use the scrollbar. When you enter text, the menu entries are limited to those entries that include the entered text.

      By default, only metrics and resources with data are shown in the menus.

      • To list all resources, expand the resource menu and clear Only show active.
      • To list all metrics, expand the metric menu and clear Only show active.
    • To enter a Monitoring filter, in the Resource type menu, select Direct filter mode. Enter the Monitoring filter in the text box.

  2. (Optional) To restrict which time series are shown, add a filter. You can add multiple filters. For example, you can view data for one zone by applying a filter. For more information about filters, see Filter charted data.

    To add a filter, click Add a filter and then select the label and label's value.

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.

Configure the chart to display multiple metrics

This option isn't available for tables or when you use MQL to configure the chart.

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

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) Configure the chart to display multiple metrics.

Select the time series data that you want to view

  1. Select a metric and resource type, or enter a Monitoring filter.

    • To select a metric and resource type, use the menus. When you select a resource, that applies a filter to the metric menu, so only metrics for that resource are listed. Similarly, when you select a metric, that applies a filter to the resource menu.

      To find a specific entry, enter text into the menu's filter area, or use the scrollbar. When you enter text, the menu entries are limited to those entries that include the entered text.

      By default, only metrics and resources with data are shown in the menus.

      • To list all resources, expand the resource menu and clear Only show active.
      • To list all metrics, expand the metric menu and clear Only show active.
    • To enter a Monitoring filter, in the Resource type menu, select Direct filter mode. Enter the Monitoring filter in the text box.

  2. (Optional) To restrict which time series are shown, add a filter. You can add multiple filters. For example, you can view data for one zone by applying a filter. For more information about filters, see Filter charted data.

    To add a filter, click Add a filter and then select the label and label's value.

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.

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:

Show the preprocessing options for a cumulative metric.

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.

Configure the chart to display multiple metrics

This option isn't available for tables or when you use MQL to configure the chart.

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

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 very Compute Engine 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 more information about using MQL, see Introduction to MQL.

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:

Example of a gauge.

The remainder of the information in this section is for the 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 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 Editing isn't shown, then click Viewing and select Switch to Editing mode.
  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

  1. Select a metric and resource type, or enter a Monitoring filter.

    • To select a metric and resource type, use the menus. When you select a resource, that applies a filter to the metric menu, so only metrics for that resource are listed. Similarly, when you select a metric, that applies a filter to the resource menu.

      To find a specific entry, enter text into the menu's filter area, or use the scrollbar. When you enter text, the menu entries are limited to those entries that include the entered text.

      By default, only metrics and resources with data are shown in the menus.

      • To list all resources, expand the resource menu and clear Only show active.
      • To list all metrics, expand the metric menu and clear Only show active.
    • To enter a Monitoring filter, in the Resource type menu, select Direct filter mode. Enter the Monitoring filter in the text box.

  2. (Optional) To restrict which time series are shown, add a filter. You can add multiple filters. For example, you can view data for one zone by applying a filter. For more information about filters, see Filter charted data.

    To add a filter, click Add a filter and then select the label and label's value.

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:

      Chart displaying the gauge configuration.

  • 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

  1. Select a metric and resource type, or enter a Monitoring filter.

    • To select a metric and resource type, use the menus. When you select a resource, that applies a filter to the metric menu, so only metrics for that resource are listed. Similarly, when you select a metric, that applies a filter to the resource menu.

      To find a specific entry, enter text into the menu's filter area, or use the scrollbar. When you enter text, the menu entries are limited to those entries that include the entered text.

      By default, only metrics and resources with data are shown in the menus.

      • To list all resources, expand the resource menu and clear Only show active.
      • To list all metrics, expand the metric menu and clear Only show active.
    • To enter a Monitoring filter, in the Resource type menu, select Direct filter mode. Enter the Monitoring filter in the text box.

  2. (Optional) To restrict which time series are shown, add a filter. You can add multiple filters. For example, you can view data for one zone by applying a filter. For more information about filters, see Filter charted data.

    To add a filter, click Add a filter and then select the label and label's value.

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:

      Chart displaying the gauge configuration.

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

Display data in tabular form on a dashboard

To view the most recent data in tabular form, add a table. Unlike gauges and scorecards, tables can display data for multiple time series. As with line charts, tables can display any metric type that has a numeric value and they can display percentiles for distribution-valued metrics.

The following screenshot illustrates a table that displays the CPU utilization of virtual machine instances:

Example of a table widget.

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

Sorting and filtering 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.

Add text to a dashboard

To add helpful information to a dashboard, add a text box. The content of a text box might be information about the dashboard, links to relevant resources, or what to do in different situations. The content of text widgets is persistent. The following screenshot illustrates a text box:

Example of a dashboard with a text widget.

The information in this section is for the Cloud Console. For information about using the Cloud Monitoring API, see Dashboard with a Text widget.

To add a text box, do the following:

  1. In the 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 Editing isn't shown, then click Viewing and select Switch to Editing mode.
  4. Select the text box widget from the Chart library, or drag this widget from the library to the graph area.
  5. Enter the text you want displayed. The text box widget supports a limited set of Markdown commands:

    • To create a header, use #. You can use multiple hash signs for different levels of headers:

        # Header
        ## Second heading
        ### Third heading
      
    • To display italic font, use *italic* or _italic_.

    • To display bold font, use **bold** or __bold__.

    • To add a link, use [link text](absolute URL). You can use any value for the link text but you must use the absolute URL.

      For example, you could write [cloud.google.com](https://cloud.google.com/) to link to cloud.google.com.

Display alerting policies on a dashboard

To view the chart associated with an alerting policy in the same context as your metric data, add an alert chart to your dashboard. Alert charts display the time series that the policy monitors, a threshold, the number of incidents associated with the policy, and whether the policy is disabled. The following screenshot illustrates an alert chart:

Example of an alert chart.

The remaining information in this section is for the Cloud Console. For information about using the Cloud Monitoring API, see Dashboard with an AlertChart widget.

To add an alert chart to a dashboard, do the following:

  1. In the 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 Editing isn't shown, then click Viewing and select Switch to Editing mode.
  4. Select the alert chart widget from the Chart library, or drag this widget from the library to the graph area.
  5. Select an existing alerting policy by using the Alert policy menu.

Viewing alerting policies

When you are viewing an alert chart, you might want more information about the alerting policy the alert chart displays. For example, you might want to review the selected notification channels or what custom documentation is included with a notification. To get information about the alerting policy, try the following:

  • To view details about the alerting policy, click the incidents chip on the alert chart, and then select View alert policy.

  • To edit the alerting policy, do the following:

    1. Ensure the dashboard is in editing mode.
    2. Select the alert chart to activate the configuration pane, and then click Edit policy.
  • To view details about the configuration of the time series the alert chart displays, click More options and select View in Metrics Explorer.

    Metrics Explorer displays a line chart configured with the same metric and filter configuration as the alert chart. Any changes you might make to the chart Metrics Explorer displays are limited to that chart. That is, you can't use Metrics Explorer to change the alerting policy.

Display log entries on a dashboard

To view log entries in the same context as your metrics, add a logs panel to a custom dashboard. Because the logs panel lets you filter your log entries, you can configure it to display only those log entries that are of interest to you.

The following screenshot illustrates a logs panel:

Example of a dashboard with a logs panel.

For information about how to display log entries on your dashboard, see View logs on a dashboard.

What's next