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.

Selecting your dashboard editor

The Dashboard Editor is the recommended dashboard editor and is enabled by default. With this editor, you can create and edit charts, indicators, and text boxes. You also have control over the shape and positioning of your dashboard widgets.

You can continue to use Legacy Dashboard Editor until it's retired. To use this editor, do the following:

  1. In the Cloud Monitoring navigation pane, select Settings.
  2. Uncheck New dashboard editor enabled on.

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 25 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 Workspace's host project includes editing permission. For more information about roles, see Access control.

Dashboard editor

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 toggle is in the on position.

  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.

Legacy dashboard editor

To add a line chart, a stacked area chart, a bar chart, or a heatmap to a dashboard by using the Legacy dashboard editor, 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. In the detail view for a dashboard, click Add Chart.

  4. Configure the chart.

  5. Click Save.

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.

Dashboard editor

To configure a line chart, a stacked area chart, a bar chart, or a heatmap chart, do the following:

Configuring a chart with Basic mode

  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.

Configuring a chart with Advanced mode

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.

  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.

Configuring a chart with MQL mode

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, see Introduction to MQL.

Legacy dashboard editor

To configure a line chart, a stacked area chart, a bar chart, or a heatmap chart, do the following:

  1. Specify the data to appear on the chart:

    1. Ensure the Metric tab is selected.

      Display the metric-selection tab.

    2. Complete the Find resource type and metric box. You can select values from the menus, or you can enter the name.

    3. (Optional) Select a subset of the data by using the Filter field.

    4. (Optional) Modify the default aggregation settings. The aggregation fields define how multiple time series are combined and how each time series is processed.

      • To group time series by a label, use the Group By field. Selecting a value for this field automatically selects a value for the Aggregator field.
      • To specify how multiple time series are combined, set the Aggregator field.
      • To configure the processing algorithm for individual time series, click Advanced Options.

    For detailed information about these fields, see Selecting data to chart.

  2. (Optional) The default view option for a chart is a line chart displayed in color mode. However, you can change both of these settings:

    • To change the chart mode, select the View options tab, and the select from the menu. The options available are dynamically set based on the chart's display-style. For more information on your choices, see View options.

    • To change the display-style for a chart, click Line to expand the pull-down menu. After you make a selection, that selection is listed adjacent to the pull-down menu. For examples of all chart types, see Chart types.

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

  4. (Optional) Update the Chart title. By default, the chart title is generated by your metric selections. You can change the title of a chart after it is created by selecting Edit in the chart toolbar.

  5. Click Save.

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.

Dashboard editor

To configure a gauge or scorecard, do one of the following:

Configuring a gauge or scorecard with Basic mode

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.

Configuring a gauge or scorecard with MQL mode

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.

Legacy dashboard editor

You can view scorecards and gauges when using the Legacy dashboard editor. To create or modify a scorecard or a gauge, you must use the Dashboard editor or the Cloud Monitoring API.

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.

Dashboard editor

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.

Legacy dashboard editor

You can view text boxes when using the Legacy dashboard editor. To create or modify a text box, you must use the Dashboard editor or the Cloud Monitoring API.

Changing a widget type

Dashboard editor

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

  1. Select the widget.
  2. 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.
  3. 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.

Legacy dashboard editor

To change the widget type of a chart, do the following:

  1. Select Edit in the chart toolbar.
  2. Select the desired plot type from the pull-down menu that is displaying the current chart style. The default style is line.

If you choose a plot type that is incompatible with a chosen chart mode, then the chart mode reverts to color mode. For example, if you have a line chart that is being viewed in X-ray mode and then select the plot type as stacked bar, the chart mode automatically switches to color mode. For information on the chart modes, see Setting view options.

Editing a dashboard widget

Dashboard editor

To edit a widget, do the following:

  1. Ensure that the Edit toggle is in the on position.
  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.

Legacy dashboard editor

To edit the configuration of a chart when using the Legacy dashboard editor, in the chart's toolbar, click Other options and select Edit.

For details on the chart toolbar and configuring the appearance of a chart, see Setting view options.

Deleting a dashboard widget

Dashboard editor

To delete a widget, do the following:

  1. Ensure that the Edit toggle is in the on position.
  2. Select the widget that you want to delete.
  3. In the chart toolbar, select Delete .

Legacy dashboard editor

To delete a chart when using the Legacy dashboard editor, click Other options in the chart's toolbar and then select Delete.

What's next