Creating and managing dashboard widgets

This page focuses on 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 numeric or distribution value, including custom metrics and logs-based metrics. Dashboard widgets can't graph string-type data.

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

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

Before you begin

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

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

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

After you select the kind of information, the next step is selecting the specific data to be displayed by the widget. This page provides general information. For detailed information, see Selecting data to chart.

You can put up to 40 widgets on a dashboard.

Adding a widget to a dashboard

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

To modify a dashboard, ensure that your Identity and Access Management role for the scoping project of a metrics scope (or the Workspace's host project) 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 Edit button is displayed. If it isn't shown, click the View only menu and select Switch to Edit 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 is displayed; however, you can modify the configuration and by using your pointer, you can change the widget size, its position on the dashboard, and its 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. A 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.

Configuring a dashboard widget

This section describes how to configure dashboard widgets.

Configuring a chart

This section describes how to configure line charts, stacked area charts, bar charts, and heatmap charts. For information on how to add a chart to your dashboard by using the Google Cloud Console, see General steps to 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 is determined by the selection 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 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 uncheck Only show active.

        • To view all metrics for the selected resource type, even those metrics without data, expand the Metric menu and then uncheck 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.

    • 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, see Selecting data to chart.

  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 unchecked.
    • To group time series by label values, check 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 list 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 list 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 configure how the data is displayed in a chart, click Settings :

    For information on chart legends, see Configuring legends.

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 is determined by the selection 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 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 uncheck Only show active.

        • To view all metrics for the selected resource type, even those metrics without data, expand the Metric menu and then uncheck 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.

    • 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, see Selecting data to chart.

  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 configure how the data is displayed in a chart, click Settings:

    For information on chart legends, see Configuring legends.

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.

Configuring a gauge or scorecard

This section describes how to configure a gauge or scorecard. For information on how to add one of these widgets to your dashboard by using the Google Cloud Console, see General steps to 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 the widget to activate its configuration pane.

  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 is determined by the selection 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 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 uncheck Only show active.

        • To view all metrics for the selected resource type, even those metrics without data, expand the Metric menu and then uncheck 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.

    • 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, see Selecting data to chart.

  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.

      An example of the gauge, when the reading is less than the warning and danger thresholds, is shown below:

      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 the configuration you select in Advanced mode can't be represented with the options available in Basic mode.

To configure a gauge or scorecard 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 is determined by the selection 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 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 uncheck Only show active.

        • To view all metrics for the selected resource type, even those metrics without data, expand the Metric menu and then uncheck 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.

    • 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, see Selecting data to chart.

  2. Select the alignment parameters.

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

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

  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.

      An example of the gauge, when the reading is less than the warning and danger thresholds, is shown below:

      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.

Configuring a text box

This section describes how to configure a text box. For information on how to add a text box to your dashboard by using the Google Cloud Console, see General steps to 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.

Changing a widget type

To change a widget's type, do the following:

  1. Ensure that the Edit button is displayed. If it isn't shown, click the View only menu and select Switch to Edit mode.
  2. Select the widget.
  3. In the configuration pane, select the current widget type. For example, if you're viewing a line chart, in the configuration pane, select Line chart.
  4. Select the new widget type from the menu.

    The menu of options lists all widget types that can chart metric data; however, a widget type is disabled if it can't display the selected data. For example, if the selected metric isn't distribution valued, then the heatmap option is disabled. Similarly, if the current widget is displaying more than one time series, then gauge and scorecard options are disabled.

If a widget type is disabled in the menu, then you can change to that widget type after modifying the current widget's configuration. For example, if you have a line chart that has time series grouped by zone, to view this data with a gauge, then you need to remove the grouping label and select a grouping function before changing the widget type.

Editing a dashboard widget

To edit a widget, do the following:

  1. Ensure that the Edit button is displayed. If it isn't shown, click the View only menu and select Switch to Edit mode.
  2. Select the widget to edit. This action activates the widget's configuration pane. If you are modifying a chart, see Setting view options for details on configuring the appearance of a chart.

    The changes that you make to the widget are saved automatically.

Deleting a dashboard widget

To delete a widget, do the following:

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

What's next