Create and manage dashboard widgets

This document describes how to build and configure dashboard widgets by using the dashboard view of the Google Cloud Console. All dashboard widgets, except text boxes, 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.

If you are interested in an alternative tool for building charts, see Metrics Explorer.

If you are interested in using the Cloud Monitoring API, see Manage dashboards by API.

Before you begin

Ensure that you have one of the roles described in Authorization.

Design a dashboard

When selecting dashboard widgets, consider what kind of information you want to view and how best to display that data:

  • To view time series data over a time interval, add a line chart, stacked area chart, stacked bar chart, or heatmap chart. Stacked bar charts are recommended for metrics with infrequent samples, such as those quota metrics that have one sample per day, while heatmap charts are recommended for distribution-type metrics.

    On this page, the term chart refers only to line charts, stacked area charts, bar charts, and heatmap charts; in this context, the term chart doesn't refer to alert charts.

  • To show if the most recent value is in a danger zone, a warning zone, or within an expected range, add a gauge or scorecard.

  • To add information about the dashboard or what to do in different situations, add a text box.

  • To view a summary of a single-condition alerting policy on a dashboard, add an alert chart. Alert charts display the time series that an alerting policy monitors and a threshold. These widgets also display chips that list the number of incidents associated with the policy and whether the policy is disabled.

After you select the kind of information, the next step is to select the specific data that the widget is to display. This page provides general information. For detailed information, see Select data to chart.

You can put up to 40 widgets on a dashboard.

Add a widget to a dashboard

This section describes how to add a widget to a dashboard. For configuration information, see Configure a dashboard widget.

To modify a dashboard, ensure that your Identity and Access Management role for the scoping project of a metrics scope includes editing permission. For more information about roles, see Access control.

To add a widget to the dashboard, do the following:

  1. In the Cloud Console, select Monitoring or click the following button:

    Go to Monitoring

  2. In the Monitoring navigation panel, click Dashboards:

    • If you want to create a new dashboard, click Create dashboard.
    • To update an existing dashboard, click the dashboard tile if shown under Recent Dashboards, or find the dashboard in the list of all dashboards and click its name.
  3. Ensure that the Editing button is displayed. If it isn't shown, click the Viewing menu and select Switch to Editing mode.

  4. Click the widget in the Chart library that you want added to the dashboard. You can also drag the widget from the library to the graph area. A preconfigured widget of the selected type is displayed.

    You can modify the widget's configuration, change its size, and change its position on the dashboard by using your pointer. For all widgets except alert charts, you can also change the widget type. For example, you can convert a line chart to a stacked bar chart.

    The following screenshot illustrates a line chart and its configuration pane:

    Example of a line chart that has been added to a dashboard.

  5. Configure the widget by using the widget's configuration pane which is displayed when the dashboard is editable and the widget is selected:

    • To quickly configure a widget, use Basic mode. This choice has minimal configuration options. A basic configuration can always be represented in the other modes.

    • To have access to all widget configuration fields, use Advanced mode. This mode provides access to most aggregation fields. This mode isn't available for all widget types. An advanced configuration might not be able to be represented in the simpler Basic mode.

    • To configure a widget using MQL, use MQL mode. An MQL configuration might not be able to be represented in the other modes.

  6. (Optional) In the dashboard toolbar, click Add chart to activate the Chart library and then repeat the previous steps for each widget that you want to add to the dashboard.

Configure a dashboard widget

This section describes how to configure dashboard widgets by using the Google Cloud Console selectors. You can also create a chart or change the configuration of a dashboard widget by editing the JSON representation of the dashboard.

Charts

This section describes how to configure line charts, stacked area charts, bar charts, and heatmap charts. For information about how to add a chart to your dashboard by using the Google Cloud Console, see Add a widget to a dashboard. If you are interested in using the Cloud Monitoring API, see Dashboard with an XyChart widget.

Basic

To configure a line, stacked area, bar, or heatmap chart by using Basic mode, do the following:

  1. Select the time series data that you want to view:

    • To modify the Resource type and the Metric, select from the menus. The Resource type menu lists every monitored resource for which there is metric data. The Metric menu determines the selections for the Resource type.

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

      • If you want to access a resource type or metric that doesn't yet have data, you need to change the default behavior:

        • To be able to select any resource type, expand the Resource type menu and then clear Only show active.

        • To view all metrics for the selected resource type, even those metrics without data, expand the Metric menu and then clear Only show active.

        • To be able to select any metric, click Close on the Resource type menu and then find the entry of interest. By clicking close on the resource type, the Metric menu includes all metrics.

        • To view or edit the resource type and metric settings as used by the Cloud Monitoring API, in the Resource type menu, click Direct filter mode.

      For more information about selecting metrics, see Selecting data to chart.

    • To add a filter, click Add a filter and then select the label and label value. 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.

  2. 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.
  3. Determine how to combine data points:

    • If the radio buttons only display percentiles, then you've selected a metric that has a distribution value. Use the radio buttons to select which percentile from the distribution to view.

    • If the radio buttons display mean, min, and max, then you've selected a metric with a numerical value. Use these buttons to specify how data points are combined as part of the charting process. For example, if a chart displays 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.

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

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

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

    For information on chart legends, see Configuring legends.

  6. (Optional) You can display multiple metrics on a single chart. If you want to display another metric on the same chart, click Add another metric and then repeat the previous steps. A chart can display a maximum of 10 metrics.

Advanced

If you are using Advanced mode and then select Basic mode, you might see error messages. These are displayed when the configuration you select in Advanced mode can't be represented with the options available in Basic mode.

To configure a line, stacked area, bar, or heatmap chart by using Advanced mode, do the following:

  1. Select the time series data that you want to view:

    • To modify the Resource type and the Metric, select from the menus. The Resource type menu lists every monitored resource for which there is metric data. The Metric menu determines the selections for the Resource type.

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

      • If you want to access a resource type or metric that doesn't yet have data, you need to change the default behavior:

        • To be able to select any resource type, expand the Resource type menu and then clear Only show active.

        • To view all metrics for the selected resource type, even those metrics without data, expand the Metric menu and then clear Only show active.

        • To be able to select any metric, click Close on the Resource type menu and then find the entry of interest. By clicking close on the resource type, the Metric menu includes all metrics.

        • To view or edit the resource type and metric settings as used by the Cloud Monitoring API, in the Resource type menu, click Direct filter mode.

      For more information about selecting metrics, see Selecting data to chart.

    • To add a filter, click Add a filter and then select the label and label value. 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.

  2. Select how the time series are preprocessed.

    Preprocessing options are displayed when the selected metric has a metric kind of delta or cumulative. The specific options available are determined by the metic's value type.

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

    When preprocessing options are available, you use the radio buttons to specify how you want the raw data processed prior to the data being aligned. In the following example, shows the options when time series for a DELTA metric are displayed:

    Show the preprocessing options for a cumulative metric.

    In this case, if you select Rate, then the data values are divided by the sampling rate. If you select No preprocessing step, then the data values aren't scaled by the sampling rate. For example, if 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.

  3. Select the alignment parameters.

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

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

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

      You must use this option if you are displaying time series on a heatmap chart. For more information, see Charting distribution metrics.

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

      • Ensure Group by is empty and select none for the Group by function.
      • Click the Group by menu and select Add all, and then select from the Group by function menu. For metrics which store a numerical value, the choice of group-by function might not produce a visibly different chart.
    • 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.

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

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

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

    For information on chart legends, see Configuring legends.

  7. (Optional) You can display multiple metrics on a single chart. If you want to display another metric on the same chart, click Add another metric and then repeat the previous steps. A chart can display a maximum of 10 metrics.

MQL

MQL is a more expressive language than the filter language used by the Basic and Advanced modes. If you configure a chart by using MQL and then select a different mode, a dialog is displayed when you might lose your MQL configuration. This dialog provides the options to cancel or continue with changing modes.

When you use MQL to configure heatmap charts, be sure to configure the aggregation options to combine all time series. If the heatmap chart displays Your MQL Query has too many time series, then modify the aggregation settings to combine all time series.

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

Gauges and scorecards

This section describes how to configure a gauge or scorecard. For information about how to add one of these widgets to your dashboard by using the Google Cloud Console, see Add a widget to a dashboard. If you are interested in using the Cloud Monitoring API, see Dashboard with a basic Scorecard.

Basic

To configure a gauge or scorecard by using Basic mode, do the following:

  1. Select an existing widget to activate its configuration pane, or add a widget to your dashboard, and then click the Basic tab.

  2. Select the time series data that you want to view:

    • To modify the Resource type and the Metric, select from the menus. The Resource type menu lists every monitored resource for which there is metric data. The Metric menu determines the selections for the Resource type.

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

      • If you want to access a resource type or metric that doesn't yet have data, you need to change the default behavior:

        • To be able to select any resource type, expand the Resource type menu and then clear Only show active.

        • To view all metrics for the selected resource type, even those metrics without data, expand the Metric menu and then clear Only show active.

        • To be able to select any metric, click Close on the Resource type menu and then find the entry of interest. By clicking close on the resource type, the Metric menu includes all metrics.

        • To view or edit the resource type and metric settings as used by the Cloud Monitoring API, in the Resource type menu, click Direct filter mode.

      For more information about selecting metrics, see Selecting data to chart.

    • To add a filter, click Add a filter and then select the label and label value. 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.

  3. Specify how the selected time series are combined into a single value.

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

  4. Configure the warning and threshold levels of a gauge or scorecard:

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

    • For scorecards, set Spark chart view. All options display the most recent.

      • Line: Show a line chart.
      • Bar: Show a bar chart.
      • Icon: Show a green, amber, or red icon.
      • Value: Display only the value.
    • For gauges and scorecards, configure the warning and danger thresholds:

      • Danger above: When value is above this threshold, set to red.
      • Warning above: When value is above this threshold, set to amber.
      • Danger below: When value is less than this threshold, set to red.
      • Warning below: When value is less than this threshold, set to amber.

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

      Chart displaying the gauge configuration.

      The following screenshot shows an example of the gauge, when the reading is less than the warning and danger thresholds:

      Example of a gauge.

      The thin outer arc displays the range of possible value and indicates warning and danger zones. The thick inner arc shows the current value.

Advanced

If you are using Advanced mode and then select Basic mode, you might see error messages. These are displayed when Basic mode can't represent the Advanced mode settings.

To configure a gauge or scorecard by using Advanced mode, do the following:

  1. Select an existing widget to activate its configuration pane, or add a widget to your dashboard, and then click the Advanced tab.

  2. Select the time series data that you want to view:

    • To modify the Resource type and the Metric, select from the menus. The Resource type menu lists every monitored resource for which there is metric data. The Metric menu determines the selections for the Resource type.

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

      • If you want to access a resource type or metric that doesn't yet have data, you need to change the default behavior:

        • To be able to select any resource type, expand the Resource type menu and then clear Only show active.

        • To view all metrics for the selected resource type, even those metrics without data, expand the Metric menu and then clear Only show active.

        • To be able to select any metric, click Close on the Resource type menu and then find the entry of interest. By clicking close on the resource type, the Metric menu includes all metrics.

        • To view or edit the resource type and metric settings as used by the Cloud Monitoring API, in the Resource type menu, click Direct filter mode.

      For more information about selecting metrics, see Selecting data to chart.

    • To add a filter, click Add a filter and then select the label and label value. 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.

  3. Select the alignment parameters.

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

  4. Select group by function. This function combines all time series together.

  5. Configure the warning and threshold levels of a gauge or scorecard:

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

    • For scorecards, set Spark chart view. All options display the most recent.

      • Line: Show a line chart.
      • Bar: Show a bar chart.
      • Icon: Show a green, amber, or red icon.
      • Value: Display only the value.
    • For gauges and scorecards, configure the warning and danger thresholds:

      • Danger above: When value is above this threshold, set to red.
      • Warning above: When value is above this threshold, set to amber.
      • Danger below: When value is less than this threshold, set to red.
      • Warning below: When value is less than this threshold, set to amber.

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

      Chart displaying the gauge configuration.

      The following screenshot shows an example of the gauge, when the reading is less than the warning and danger thresholds:

      Example of a gauge.

      The thin outer arc displays the range of possible value and indicates warning and danger zones. The thick inner arc shows the current value.

MQL

MQL is a more expressive language than the filter language used by the Basic and Advanced modes. If you configure a chart by using MQL and then select a different mode, a dialog is displayed when you might lose your MQL configuration. This dialog provides the options to cancel or continue with changing modes. For more information, see Introduction to MQL.

When you use MQL to configure gauges and scorecards, be sure to configure the aggregation options to combine all time series. If the widget displays Your MQL Query has too many time series, then modify the aggregation settings to combine all 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, if your VM instances are in multiple zones, then 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 all 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 all 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 one time series.

Tables

This section describes how to configure a table. For information about how to add a table to your dashboard by using the Google Cloud Console, see Add a widget to a dashboard. If you are interested in using the Cloud Monitoring API, see Dashboard with a TimeSeriesTable widget.

Table widgets can display any metric type that has a numeric value. Table widgets can display percentiles for distribution-valued metrics.

To configure a table, do the following:

  1. Specify the metric the table is to display, the filters, and how you want to the time series to be combined. For tables, these steps are identical to the steps you use when you Configure a chart.

    To configure a table, you can use Basic, Advanced, or MQL mode.

  2. (Optional) To change the table name, use the Chart title field in the configuration pane.

After a table is configured, you have the following options:

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

  2. To page through the results, use the Forward and Backward buttons.

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

  4. To list only select rows, add one or more filters. When you add a filter, you select a filter property and a filter value. If you don't specify the OR operator between two filters, then a logical-AND joins the 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 only lists rows where the Name field includes the value demo.

Text boxes

This section describes how to configure a text box. For information about how to add a text box to your dashboard by using the Google Cloud Console, see Add a widget to a dashboard. If you are interested in using the Cloud Monitoring API, see Dashboard with a Text widget.

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.

Alert charts

To configure an alert chart, you associate it with a single-condition alerting policy. For information about how to add an alert chart to your dashboard by using the Google Cloud Console, see Add a widget to a dashboard. If you want to use the Cloud Monitoring API, see Dashboard with an AlertChart widget.

To associate an alert chart with an alerting policy, in the configuration pane of the Alert chart widget, you use the Alert policy menu to select an alerting policy. If an alert policy can't be selected in the menu, then an alert chart can't represent that policy.

After you select an alerting policy, time-series data, a threshold, and chips that show the number of open incidents and whether the policy is disabled, are displayed. The following screenshot illustrates an alert chart:

Example of an alert chart.

The previous screenshot illustrates an alert chart for an alerting policy that is monitoring the CPU usage of two different virtual machines. The dashed red line shows the condition threshold, which is set to 50%. The green chip with the label No incidents indicates that there are no open incidents for the alerting policy.

To get information about the alerting policy that an alert chart displays, do one of the following:

  • To activate a tooltip that displays the alert details, place your pointer on an entry in the Alert policy menu.
  • To access the details page of the alerting policy, click the incidents chip and select View alert policy.

To view details about the configuration of the alert chart, click More options and select View in Metrics Explorer. In Metrics Explorer, a line chart is displayed that contains the same metric and filter configuration as the alert chart. If you modify the chart displayed in Metrics Explorer, you can't apply those changes to the alerting policy or to the alert chart displayed on a dashboard.

If you use the Cloud Monitoring API and want the JSON representation of an alert chart, then click JSON Editor in the dashboard toolbar.

Change a widget type

You can change a widget's type when the destination widget can represent the data shown by the source widget. For example, you can always change a line chart into a stacked-area or stacked-bar chart. Similarly, you can always convert a gauge, which shows exactly one time series, into a line chart. However, you might not be able to convert a line chart, which can show many time series, into a gauge.

You can't change the type of an alert chart or a table. You also can't convert any widget to an alert chart or to a table.

For all other widget type conversions, do the following:

  1. Ensure that the Editing button is displayed. If it isn't shown, click the Viewing menu and select Switch to Editing mode.
  2. Select the widget.
  3. In the configuration pane, click the name of the current widget type, and then make a selection from the menu. For example, to convert a line chart to a stacked area chart, in the configuration pane, click Line chart and then select Stacked area chart.

    The menu of options lists all widget types that can chart metric data; however, a widget type is disabled when it can't display the selected data:

    • When the charted metric isn't distribution valued, the heatmap option is disabled.
    • When the current widget is displaying more than one time series, gauge and scorecard options are disabled.
    • When the left Y-axis is configured for a line chart, all widget types except stacked area and stacked bar are disabled.

Edit a dashboard widget

To edit a widget, do the following:

  1. Ensure that the Editing button is displayed. If it isn't shown, click the Viewing menu and select Switch to Editing mode.

  2. Select the widget to activate the widget's configuration pane.

  3. (Optional) If you want to edit the widget by using the JSON editor, then click JSON editor to open that editor.

  4. Modify the widget by using the widget's configuration pane or the JSON editor:

    • If you use the configuration pane, your changes are saved automatically unless you disable autosave. If you are modifying a chart, see Setting view options for details on configuring the appearance of a chart.
    • If you use the JSON editor, then you must click Apply changes to save your changes. By default, only the chart-specific section of the JSON is expanded. To view the entire dashboard definition, click Show more:

      Illustrate the expand button on the JSON editor.

Delete a dashboard widget

Deleting an alert chart doesn't delete the alerting policy whose data was displayed on the chart. Therefore, you might receive notifications from that policy after the alert chart is deleted. To manage your alerting policies, go to the Alerting page in the Google Cloud Console.

To delete a widget, do the following:

  1. Ensure that the Editing button is displayed. If it isn't shown, click the Viewing menu and select Switch to Editing mode.
  2. Select the widget that you want to delete.
  3. In the chart toolbar, select Delete.

What's next