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. These dashboards can also display service-level objectives (SLOs) for a set of services.

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, and you can organize your widgets into named groups.

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 charts and tables by using the 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 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 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) 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:

Example of Metrics Explorer configuration with two 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) 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.

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.

(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:

Example of Metrics Explorer configuration with two metrics.

(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 very 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.

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 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 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:

      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

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:

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

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 a table widget.

For information about how to add tables 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 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 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 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 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 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 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.

Deleting alerting policies

If you delete the alerting policy associated with an alert chart, then the alert chart no longer displays any data. For more information, see Alert chart doesn't display any data.

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 custom dashboard.

Display SLOs on a dashboard

To view the health, compliance, or error budget of a service-level objective (SLO) for a service, add an SLO chart to a custom dashboard. An SLO chart provides a summary of the performance of a service relative to a configured SLO. By using SLO charts, you can create a custom dashboard that shows the status of all SLOs for a set of services.

Before you can use an SLO chart, you must have services configured. For information about services and SLOs, see SLO monitoring.

The following screenshot illustrates an SLO chart that displays the error budget for an SLO:

Example of an SLO chart that shows the remaining error budget for an SLO.

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

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

  1. In the 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 the SLO chart widget from the Chart library, or drag this widget from the library to the graph area.
  5. Select an existing service from the Service menu.
  6. Select an existing SLO for the service from the Service-level Objectives menu.

    If the chosen service has no SLOs, then a message tells you that must create one. To add an SLO, click Create SLO. For more information about creating SLOs, see Creating an SLO. After you create a SLO, select it and proceed to the next step.

  7. Select a SLO metric from the Service Level Objective Chart Type menu. You can select health, compliance, and absolute or fractional error budget. For more information about SLO metrics, see Retrieving SLO data.

Organize dashboard widgets

To improve the usability of a dashboard with many widgets, use collapsible group widgets. A collapsible group widget is a container for other widgets, so you can view and manage those widgets as a collection. For example, a collapsible group widget might contain charts that display VM metrics and display alerting policies that monitor VMs.

To add a collapsible group widget, do the following:

  1. In the 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. In the dashboard toolbar, ensure that Mosaic is selected.
  5. Select the collapsible group widget from the Chart library, or drag this widget from the library to the graph area.
  6. (Optional) Enter a descriptive title in the configuration pane. The title is shown on the widget.
  7. (Optional) Set the default view to expand or collapse the group. When a collapsible group widget is collapsed, Monitoring retrieves the data for the widgets in the group at a lower priority than for other widgets.
  8. Add widgets to the group by doing one of the following:

    • Drag an existing widget to the group.
    • Drag a widget from the chart library to the group.
  9. (Optional) Use your pointer to resize and reposition widgets within the group.

To remove a widget from a collapsible group widget, you can delete the widget or drag it to unused space in the dashboard.

To remove the grouping, select the collapsible group widget, and in the widget's toolbar, select Cancel.

What's next