Add charts and tables to a custom dashboard

This document describes how to add charts, tables, gauges, and scorecards to a custom dashboard by using the Google Cloud console. You can display metric data over a time interval by adding a line chart, a stacked-area chart, a bar-chart, or a heatmap chart. If you are only interested in the most recent measurements, then add a table, a pie chart, a gauge, or a scorecard. Gauges and scorecards change color based on how the most recent value compares to warning and danger thresholds.

The visualizations you can add to dashboards are collectively called widgets. For general information about the different widget types, see Dashboards overview.

Charts, tables, gauges, and scorecards on custom dashboards can display any metric type that has a numeric or distribution value, including user-defined metrics and log-based metrics. Charts can't graph string-type data.

This document describes how to add charts, tables, gauges, and scorecards to a custom dashboard that display time-series data. For information about adding other types of widgets to your dashboards, see the following documents:

For information about the Cloud Monitoring API, see Manage dashboards by API.

Before you begin

  • To get the permissions that you need to create and modify custom dashboards by using the Google Cloud console, ask your administrator to grant you the Monitoring Editor (roles/monitoring.editor) IAM role on your project. For more information about granting roles, see Manage access.

    You might also be able to get the required permissions through custom roles or other predefined roles.

    For more information about roles, see Control access with Identity and Access Management.

  • You can put up to 40 widgets on a dashboard.

  • To add a widget to a dashboard, you can either select the visualization and then configure the widget, or you can select the data type first and then configure the visualization.

    For example, to add a table that displays the CPU utilization of your VM instances to a dashboard, you can do either of the following:

    • Select the Table widget and then configure that widget to display the CPU utilization of your VM instances.
    • Select the Metric data type, configure the widget to display the CPU utilization of your VM instances, and then change the widget type to Table.

    The instructions on this page assume that you select the data type first, and then configure how that data is displayed.

Add charts and tables to a dashboard

This section describes how to configure charts and tables by using the Google Cloud console:

  • Charts show data over time and there are four styles available: Line, Stacked area, Stacked bar, and Heatmap. After a chart is configured, you can change its widget type. For information about why you might select a specific style, see Charts that show data over time.

    For information about using the Cloud Monitoring API to configure a chart, see Dashboard with an XyChart widget.

  • Tables contain one row for each monitored time series and they only show the most recent value. There are two styles of tables. The Table widget displays a numeric value like "25%". The Top List widget displays both the value and a visual indicator of the value compared to the range of possible values. You can change between these widget types. For more information and an example, see Display data in tabular form on a dashboard.

    For information about using the Cloud Monitoring API to configure a table, see Dashboard with a TimeSeriesTable widget.

To add a chart or a table to a dashboard, do the following:

  1. In the navigation panel of the Google Cloud console, select Monitoring, and then select  Dashboards:

    Go to Dashboards

  2. Do one of the following:

    • To create a new dashboard, select Create dashboard.
    • To update an existing dashboard, find the dashboard in the list of all dashboards and select its name.
  3. In the toolbar, click  Add widget.

  4. In the Add widget dialog, select  Metric.

  5. Specify the data to display on the chart. You can use a menu-driven interface, Monitoring Query Language (MQL), PromQL, or you can enter a Monitoring filter:

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

      1. In the Metric element, expand the Select a metric menu.

        The Select a metric menu contains features that help you find the metric types available:

        • To find a specific metric type, use the Filter bar. For example, if you by enter util, then you restrict the menu to show entries that include util. Entries are shown when they pass a case-insensitive "contains" test.

        • To show all metric types, even those without data, click Active. By default, the menus only show metric types with data.

        For example, you might make the following choices:

        1. In the Active resources menu, select VM instance.
        2. In the Active metric categories menu, select uptime_check.
        3. In the Active metrics menu, select Request latency.
        4. Click Apply.
      2. Optional: To specify a subset of data to display, in the Filter element, select Add filter, and then complete the dialog. For example, you can view data for one zone by applying a filter. You can add multiple filters. For more information, see Filter charted data.

      For more information, see Select the data to chart.

    2. Combine and align time series:

      • To display every time series, in the Aggregation element, set the first menu to Unaggregated and the second menu to None.

      • To combine time series, in the Aggregation element, do the following:

        1. Expand the first menu and select a function.

          The chart is refreshed and displays a single time series. For example, if you select Mean, then the displayed time series is the average of all time series.

        2. To combine time series that have the same label values, expand the second menu, and then select one or more labels.

          The chart is refreshed and shows one time series for each unique combination of label values. For example, to display on time series per zone, set the second menu to zone.

          When the second menu is set to None, the chart displays one time series.

      • Optional: To configure the spacing between data points, click Add query element, select Min Interval, and then enter a value.

      For more information about grouping and alignment, see Choose how to display charted data.

    3. Optional: To display only the time series with the highest or lowest values, use the Sort & Limit element.

    MQL

    1. In the toolbar of the query-builder pane, select the button whose name is either  MQL or  PromQL.
    2. Verify that MQL is selected in the Language toggle. The language toggle is in the same toolbar that lets you format your query.
    3. Enter your query into the query editor. For example, to chart the CPU Utilization of the VM instances in your Google Cloud project, use the following query:

      fetch gce_instance
      | metric 'compute.googleapis.com/instance/cpu/utilization'
      | group_by 1m, [value_utilization_mean: mean(value.utilization)]
      | every 1m
      

      For more information about MQL, see the following documents:

    PromQL

    1. In the toolbar of the query-builder pane, select the button whose name is either  MQL or  PromQL.
    2. Verify that PromQL is selected in the Language toggle. The language toggle is in the same toolbar that lets you format your query.
    3. Enter your query into the query editor. For example, to chart the average CPU utilization of the VM instances in your Google Cloud project, use the following query:

      avg(compute_googleapis_com:instance_cpu_utilization)
      

      For more information about using PromQL, see PromQL in Cloud Monitoring.

    Monitoring filter

    1. In the Metric element, click Help, and then select Direct Filter Mode.

      The Metric and Filter elements are deleted, and a Filters element that lets you enter text, is created.

      If you selected a resource type, metric, or filters before switching to Direct Filter Mode mode, then those settings are shown in the field of the Filters element.

    2. Enter a Monitoring filter in the field of the Filters element.
    3. Combine and align time series:

      • To display every time series, in the Aggregation element, set the first menu to Unaggregated and the second menu to None.

      • To combine time series, in the Aggregation element, do the following:

        1. Expand the first menu and select a function.

          The chart is refreshed and displays a single time series. For example, if you select Mean, then the displayed time series is the average of all time series.

        2. To combine time series that have the same label values, expand the second menu, and then select one or more labels.

          The chart is refreshed and shows one time series for each unique combination of label values. For example, to display on time series per zone, set the second menu to zone.

          When the second menu is set to None, the chart displays one time series.

      • Optional: To configure the spacing between data points, click Add query element, select Min Interval, and then enter a value.

      For more information about grouping and alignment, see Choose how to display charted data.

  6. Optional: Configure the chart to display multiple metric types.

    1. Select Add query. A new query is added. For example, a query with the label B might be added.

    2. For the new query, in the Metric element, select a resource type and metric type. You can also add filters, combine time series, and sort and limit the number of displayed time series.

    The following screenshot illustrates the Metrics Explorer display when there are two metric types charted:

    Example of Metrics Explorer with two metric types.

    MQL

    Not supported.

    PromQL

    Not supported.

    Monitoring filter

    Not supported.

  7. Optional: Configure the chart to display a ratio of metric types.

    1. Configure the chart to display two metric types that have the same metric kind. For example, both are GAUGE metrics.
    2. Ensure that the value of the Min Interval field is the same for both metric types. To access this field, click Add query element and select Min Interval.
    3. Update the aggregation fields.

      We recommend that the labels for the denominator metric type match the values set for the numerator metric type. For example, you might select the zone label for the numerator and denominator.

      You aren't required to use the same set of labels for both metric types; however, you can only select labels that are common to both metric types.

    4. In the toolbar of the query pane, select Create ratio, and then complete the dialog.

      After you create the ratio, three queries are shown:

      • A/B Ratio identifies the ratio query.
      • A identifies the query for the numerator.
      • B identifies the query for the denominator.

      The following example illustrates a ratio that compares the sum of the bytes written to disk per zone, to the total number of bytes written to disk:

      Example of a ratio of metrics.

    5. Optional: To switch the numerator and denominator metrics, in the Ratio element, expand the menu, and then make a selection.

    MQL

    1. In the toolbar of the query-builder pane, select the button whose name is either  MQL or  PromQL.
    2. Verify that MQL is selected in the Language toggle. The language toggle is in the same toolbar that lets you format your query.
    3. Enter your query into the query editor. MQL lets you compute a ratio of two different metrics, and it lets you filter a single metric by a label and then compute the ratio. The following query computes the ratio of responses with a value of 500 to the total number of responses:

      fetch https_lb_rule::loadbalancing.googleapis.com/https/request_count
      | {
          filter response_code_class = 500
        ;
          ident
        }
      | group_by [matched_url_path_rule]
      | outer_join 0
      | div
      

      For more information about MQL, see the following documents:

    PromQL

    1. In the toolbar of the query-builder pane, select the button whose name is either  MQL or  PromQL.
    2. Verify that PromQL is selected in the Language toggle. The language toggle is in the same toolbar that lets you format your query.
    3. Enter your query into the query editor. For example, to chart the ratio of average latency of your my_summary_latency_seconds metric, use the following query:

      sum without (instance)(rate(my_summary_latency_seconds_sum[5m])) /
      sum without (instance)(rate(my_summary_latency_seconds_count[5m]))
      

      For more information about using PromQL, see PromQL in Cloud Monitoring.

    Monitoring filter

    Not supported.

  8. Optional: To change the visualization, in the Display pane, click Widget type and then make a selection.

    The Widget type menu lists all widget types that can display the same type of data; however, some widgets might not be enabled. For example, consider a chart on a dashboard configured to display one metric type. The line chart displays multiple time series, and that each measured value is a double:

    • Table, Pie chart, Line chart, Stacked bar chart, and Stacked area chart widgets are listed as Compatible. You can select any of these types.

    • Scorecard and Gauge widgets are listed as Compatible with adjustments because these widgets can display only a single time series. To enable these widget types, modify the grouping configuration.

    • The Heatmap widget is disabled because these widgets can only display distribution-valued data.

    • The logs panel isn't listed because the logs panel can't display time-series data.

  9. Optional: To change how the chart displays the selected data, use the options in the Display pane:

  10. To apply your changes to the dashboard, in the toolbar, click Apply. To discard your changes, click Cancel.

  11. To save your modified dashboard, in the toolbar, click Save.

Display only the most recent data

Monitoring provides you with several ways to visualize only the most recent measurements, instead of viewing the history of measurements:

  • To graphically display the most recent value of each time series, where each value is shown as a fraction of the sum of all values, add a pie chart. You can configure these charts to display the total value.

  • To display the most recent value of each time series in a tabular form, add a table. You can limit the number of rows in a table, and you can configure the rows of a table to show a value as compared to a range of values.

  • To get a green, amber, or red indication of the most recent value as compared to a set of thresholds, add a gauge or scorecard to the dashboard.

Graph the most recent data with a pie chart

To view the most recent data as a fraction of the total, add a pie chart. Like tables, a pie chart can display any metric type that has a numeric value, and they can display percentiles for distribution-valued metrics. Each time series contributes one slice to the pie.

The following screenshot illustrates a dashboard that displays the CPU utilization of virtual machine instances by using two different configurations of a Pie chart widget:

Example of **PieChart** widgets.

For information about how to add pie charts to a dashboard, see the following documents:

  • Google Cloud console: See the section titled Add charts and tables in this document.

    • After you select the data to chart, in the Display pane, set the Widget type field to Pie chart.
    • To display the total value, set the Chart type field to Donut.
  • Cloud Monitoring API: See Dashboard with a PieChart widget.

Display the most recent data in tabular form

To view the most recent data in tabular form, add a table. Tables can display any metric type that has a numeric value, and they can display percentiles for distribution-valued metrics. Tables only show the most recent value, similar to the behavior of gauges and scorecards. However, unlike gauges and scorecards, tables contain one row for each monitored time series.

There are two styles of tables. The Top List widget is preconfigured to have two columns and to limit the number of rows. One column in the Top List widget displays a label like instance_id and the other displays both the value and a visual indicator of the value compared to the range of possible values. The Table widget is preconfigured to display one column for each label with more than one unique value, one row for each time series, and a numeric value like "25%".

Both widgets are represented by the same data structure. Therefore, after you add one of these widgets to your dashboard, you can limit the number of rows shown, change the columns displayed by the table, and change how the value is represented.

The following screenshot illustrates a dashboard that displays the CPU utilization of virtual machine instances by using a Top List widget and a Table widget:

Example of **Top List** and **Table** widgets.

For information about how to add tables to a dashboard, see the following documents:

Sort and filter tables

You can change the order of the rows in the table display, and you can filter the table contents so that only specific rows are shown. These settings aren't persistent. When you leave the dashboard page or when you reload the dashboard, the sorting and filtering options you applied are discarded.

You have the following sorting and filtering options:

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

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

  • To list only specific rows, add one or more filters. You can add multiple filters. When you don't specify the OR operator between two filters, a logical-AND joins those 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 lists only rows where the Name field includes the value demo.

Display the most recent data with warning or error indication

To view the most recent measurement as compared to a color-coded set of thresholds, add a gauge or a scorecard. Gauges display only the most recent measurement while scorecards also show a history of recent measurements. The background color of these widgets is also color-coded. When the most recent value is within expected ranges, the widget color is white. When the value is in a warning range, the widget becomes amber. Similarly, when the value is in a danger range, the widget becomes red.

Both widgets display a single time series. The following screenshot shows an example of a gauge when the most recent measurement is less than the warning and danger thresholds:

Example of a gauge.

The remainder of the information in this section is for the Google Cloud console. For information about using the Cloud Monitoring API, see Dashboard with a basic Scorecard.

To add a gauge or scorecard to a dashboard, do the following:

  1. In the navigation panel of the Google Cloud console, select Monitoring, and then select  Dashboards:

    Go to Dashboards

  2. Do one of the following:

    • To create a new dashboard, select Create dashboard.
    • To update an existing dashboard, find the dashboard in the list of all dashboards and select its name.
  3. In the toolbar, click  Add widget.

  4. In the Add widget dialog, select  Metric.

  5. Specify the data to display on the chart. You can use a menu-driven interface, Monitoring Query Language (MQL), PromQL, or you can enter a Monitoring filter:

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

      1. In the Metric element, expand the Select a metric menu.

        The Select a metric menu contains features that help you find the metric types available:

        • To find a specific metric type, use the Filter bar. For example, if you by enter util, then you restrict the menu to show entries that include util. Entries are shown when they pass a case-insensitive "contains" test.

        • To show all metric types, even those without data, click Active. By default, the menus only show metric types with data.

        For example, you might make the following choices:

        1. In the Active resources menu, select VM instance.
        2. In the Active metric categories menu, select uptime_check.
        3. In the Active metrics menu, select Request latency.
        4. Click Apply.
      2. Optional: To specify a subset of data to display, in the Filter element, select Add filter, and then complete the dialog. For example, you can view data for one zone by applying a filter. You can add multiple filters. For more information, see Filter charted data.

      For more information, see Select the data to chart.

    2. Combine the time series by using the Aggregation fields:

      • Expand the first menu and select the function that combines the time series.
      • Expand the second menu and ensure that no labels are selected.

    MQL

    1. In the toolbar of the query-builder pane, select the button whose name is either  MQL or  PromQL.
    2. Verify that MQL is selected in the Language toggle. The language toggle is in the same toolbar that lets you format your query.
    3. Enter your query into the query editor. You must ensure that the aggregation fields are set to combine all time series. For example, to chart the CPU utilization of the VM instances in your Google Cloud project, use the following query:

      fetch gce_instance
      | metric 'compute.googleapis.com/instance/cpu/utilization'
      | group_by 1m, [value_utilization_mean: mean(value.utilization)]
      | every 1m
      | group_by [], [value_utilization_mean_mean: mean(value_utilization_mean)]
      

      For more information about MQL, see the following documents:

    PromQL

    1. In the toolbar of the query-builder pane, select the button whose name is either  MQL or  PromQL.
    2. Verify that PromQL is selected in the Language toggle. The language toggle is in the same toolbar that lets you format your query.
    3. Enter your query into the query editor. For example, to chart the average CPU utilization of the VM instances in your Google Cloud project, use the following query:

      avg(compute_googleapis_com:instance_cpu_utilization)
      

      For more information about using PromQL, see PromQL in Cloud Monitoring.

    Monitoring filter

    1. In the Metric element, click Help, and then select Direct Filter Mode.

      The Metric and Filter elements are deleted, and a Filters element that lets you enter text, is created.

      If you selected a resource type, metric, or filters before switching to Direct Filter Mode mode, then those settings are shown in the field of the Filters element.

    2. Enter a Monitoring filter.
    3. Combine the time series by using the Aggregation fields:

      • Expand the first menu and select the function that combines the time series.
      • Expand the second menu and ensure that no labels are selected.

  6. In the Display pane, configure the gauge or scorecard:

    1. Click Widget type and select Gauge or Scorecard.

    2. For gauge widgets, click Gauge range, and then set the minimum and maximum values. When a gauge displays a percentage, set these values to 0 and 1 respectively.

    3. Click Gauge threshold, and then set the warning and danger thresholds. Threshold fields that are empty aren't used.

      For the gauge displayed previously, two thresholds are set. Values higher than 0.9 are in the danger range. Values higher than 0.7 but not in the danger range, are in the warning range.

    4. For scorecards, click Spark chart view, then expand the menu of options, and then select the display style.

  7. To apply your changes to the dashboard, in the toolbar, click Apply. To discard your changes, click Cancel.

  8. To save your modified dashboard, in the toolbar, click Save.

What's next

You can also add the following widgets to your custom dashboards:

For information about exploring charted data and filtering your dashboards, see the following documents: