Creating and managing dashboard widgets

This page focuses on building and editing charts from the dashboard view. If you are interested in Metrics Explorer, an alternative tool for building charts, see Using Metrics Explorer.

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 cannot graph string-type data. The following screenshot is an example of a line chart in color mode. For these charts, a unique color is assigned to each time series.

Example of a line chart in color mode.

Before you begin

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

Selecting your dashboard editor

There are two dashboard editors: Preview and Classic.

  • Classic: With this editor, dashboards are optimized for line charts and displays charts in a grid pattern. You can convert a chart of one widget type to a different widget type. For example, you can convert a line chart to a stacked bar chart. You can view, but not create or modify, scorecards, gauges, or text boxes.

    To use this editor, in the details pane of the dashboard, select Classic.

    To switch to the Preview editor, in the details pane of the dashboard, click Classic and then select Preview new Dashboard Editor:

    Select preview editing.

  • Preview: With this editor, dashboards have a rich set of widgets and flexible size and positioning options for charts. With this editor, you can create and edit scorecards, gauges, and text boxes. However, you cannot convert one widget type to a different widget type. For example, you cannot convert a line chart to a stacked bar chart.

    When you add widgets to a dashboard, you have multiple configuration options:

    • To quickly configure a widget, use the Basic mode. This choice has minimal configuration options.

    • To have access to all widget configuration fields, use the Advanced mode. This mode provides access to most aggregation fields.

    • To configure a widget using a query language, use the MQL mode.

    To use this editor, in the details pane of the dashboard, select Preview.

    To switch to the Classic editor, in the details pane of the dashboard, click Preview and then select View classic Dashboard Editor:

    Select classic editing.

Adding a dashboard widget

The process of designing a dashboard involves the following tasks:

  1. Determining 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. Heatmaps are recommended for distribution-type metrics. With these charts, you can view the entire distribution and overlay percentile lines.

      You can configure these charts to display a threshold, show only outliers, or compare current data to past data.

    • 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. You can create and modify these widgets by using the Preview editor or the Cloud Monitoring API.

    • To add information about the dashboard or what to do in different situations, add a text box. You can create and edit this widget by using the Preview editor or the Cloud Monitoring API.

    For examples of the widgets types, see Dashboard widgets.

  2. Identifying the specific data to appear on the chart. For more information, see Selecting data to chart.

You can put up to 25 widgets on a dashboard.

General steps to add a widget to a dashboard

This section describes how to add a widget to a dashboard. For information on configuring that widget, see Configuring a dashboard widget.

Preview 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 the dashboard toolbar displays Preview and 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.

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

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

    By using your pointer, you can change the widget size and its position on the dashboard.

  5. Configure the widget by using the widget's configuration pane. The configuration pane is displayed when the dashboard is in edit mode and the widget is selected:

    • To quickly configure a widget, use the 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 the 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 a query language, use the MQL mode. With this mode, you have access to the Query Editor. If you use MQL, that configuration cannot be represented by the other modes. For information about MQL, see Introduction to MQL.

  6. Click Save dashboard.

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

Classic editor

To add a line chart, a stacked area chart, a bar chart, or a heatmap to a 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 the dashboard toolbar displays Classic.

  4. In the detail view for a dashboard, click Add Chart. This button is in the dashboard toolbar if you have editing permissions for the Workspace.

  5. Configure the chart.

  6. Click Save.

Configuring a dashboard widget

This section describes how to configure dashboard widgets.

Configuring a chart

This section describes how to configure a chart. 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.

Preview 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, metric, and filter 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

  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, metric, and filter 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, the selection is set to Delta:

    Show the preprocessing options for a cumulative metric.

    The difference between selecting delta and rate is the units. When rate is selected, the data is transformed into a delta metric and then the values are divided by the sampling rate. For example, if the y-axis units are MiB when delta is selected, 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.

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

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

Preview editor

To configure a gauge or scorecard, 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, metric, and filter 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.

Classic editor

You can view scorecards and gauges when using the Classic editor. To create or modify a scorecard or a gauge, you must use the Preview 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.

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

Classic editor

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

Changing a widget type

Preview editor

You cannot change the widget type. For example, if you selected a line chart, you cannot convert that to a heatmap chart.

Classic 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

Preview editor

To edit a widget, do the following:

  1. Ensure the dashboard toolbar displays Preview and 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.
  3. Click Save dashboard.

Classic editor

To edit the configuration of a chart, 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

Preview editor

To delete a widget, do the following:

  1. Ensure the dashboard toolbar displays Preview and that the Edit toggle is in the on position.
  2. Select the widget that you want to delete.
  3. In the configuration toolbar, select Delete .
  4. Click Save dashboard.

Classic editor

To delete a chart, click Other options in the chart's toolbar and then select Delete.

What's next