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 and logs panels, 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.

For information about a standalone charting tool, see Metrics Explorer.

For information about 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 value of a metric is in a danger zone, 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.

  • To view the log entries stored in your Google Cloud project, or in the metrics scope of your Google Cloud project, add a logs panel. The logs panel supports querying using the Cloud Logging query language, and you can open Logs Explorer from this panel.

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 dashboard widget

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:

    • 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. If Editing isn't shown, then click Viewing 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 dashboard widget. For information about 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.

    This option isn't available for heatmap charts, as these charts can only display a single time series.

  3. Use the radio buttons, when shown, to specify how to combine data points.

    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.

    When you configure a chart to display multiple metrics, 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.

    This option isn't available for heatmap charts.

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

When you are using Advanced mode and then select Basic mode, a dialog might be displayed. The dialog is shown 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.

    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.

    In this case, 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.

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

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

    When you configure a chart to display multiple metrics, 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.

    This option isn't available for heatmap charts.

  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. 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. When 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 the time series. If a heatmap chart displays Your MQL Query has too many time series, then modify the aggregation settings to combine the time series.

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

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 dashboard widget. For information about 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 higher than this threshold, set to red.
      • Warning above: When value is higher than 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

When you are using Advanced mode and then select Basic mode, a dialog might be displayed. The dialog is shown 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 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 the group by function. This function combines the 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 higher than this threshold, set to red.
      • Warning above: When value is higher than 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. When 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 the time series. When the widget displays Your MQL Query has too many time series, modify the aggregation settings to combine the 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.

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 dashboard widget. For information about 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 Next and Previous 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. When you don't specify the OR operator between two filters, 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 dashboard widget. For information about how to use 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. The instructions in this section are for the Google Cloud Console. For information about how to use the Cloud Monitoring API, see Dashboard with an AlertChart widget.

To associate an alert chart with an alerting policy, do the following:

  1. Add an alert chart widget to your dashboard. For information about this step, see Add dashboard widget.

  2. Do one of the following:

    • When the alerting policy that you want to display exists, select that policy by using the Alert policy menu in the configuration pane of the Alert chart widget.

    • When the alerting policy that you want to display doesn't exist, click Create alert policy in the configuration pane of the Alert chart widget. For information about how to complete the dialog, see Create an alerting policy.

      Don't configure your alerting policy to contain more than one condition. An alert chart can't display a policy that contains more than one condition.

      After you create the policy, the alert chart automatically displays it.

An alert chart displays time-series data, a threshold, the number of open incidents, and whether the policy is disabled. The following screenshot shows an alert chart for an alerting policy that is monitoring the CPU usage of two different virtual machines:

Example of an alert chart.

In the previous screenshot, the dashed line shows the condition threshold, which is set to 50%. The No incidents label indicates that there are no open incidents for the alerting policy.

You can view and edit the alerting policy that an alert chart displays:

  • To edit the alerting policy displayed by an alert chart, select the alert chart to activate the configuration pane, and then click Edit policy.

  • To view details about the alerting policy displayed by the alert chart, click the incidents chip on the alert chart, and then select View alert 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.

The JSON representation is useful when you use the Cloud Monitoring API. To view the JSON representation of an alert chart, click JSON Editor in the dashboard toolbar.

Logs panels

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

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, a table, or a logs panel. You also can't convert any of these widget types.

For information about how to convert a widget to an alert chart, see Change to alert chart.

For all other widget type conversions, do the following:

  1. If Editing isn't shown, then click Viewing 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.

Change to alert chart

You can convert a line chart to an alert chart when the line chart displays a single metric and at most one threshold.

To convert a line chart to an alert chart, do the following:

  1. If Editing isn't shown, then click Viewing and select Switch to Editing mode.

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

  3. Click More options and select Convert to alert chart.

    When you make this selection, the Create alert policy dialog opens and the metric, filter, and grouping selections from your chart are applied to the alerting condition. To complete the alerting policy, configure the condition trigger, specify the notification channels and documentation, and then click Create policy. For more information, see Create an alerting policy.

To manage the new policy, go to the Alerting page in the Google Cloud Console.

Edit a dashboard widget

To edit a widget, do the following:

  1. If Editing isn't shown, then click Viewing and select Switch to Editing mode.

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

  3. (Optional) To edit the widget by using the JSON editor, click JSON editor to open that editor.

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

    • Configuration pane: Your changes are saved automatically unless you disable autosave. For information about how to modify the appearance of a chart, see Setting view options.
    • JSON editor: To save your changes, click Apply 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. If Editing isn't shown, then click Viewing 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