Add text and groupings to a dashboard

This document describes how you can add helpful information to a dashboard, and how you can group widgets on a dashboard. For example, you might want to add information about the dashboard, add links to relevant resources, or what to do in different situations. When a dashboard contains many widgets, you can improve the usability of the dashboard by grouping them.

For information about the Cloud Monitoring API, see Create and 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 to projects, folders, and organizations.

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.

Add text to a dashboard

The following screenshot illustrates a text widget:

Example of a dashboard with a text widget.

The information in this section is for the Google Cloud console. For information about using the Cloud Monitoring API, see Dashboard with a Text widget.

To add a text widget to a dashboard, do the following:

In the Google Cloud console, go to the Dashboards page:
Go to Dashboards

If you use the search bar to find this page, then select the result whose subheading is Monitoring.
Select a dashboard or click Create dashboard.
In the toolbar, click Add widget.
In the Add widget dialog, go to the Layout section, and then select Text.
Add a title.
In the Content pane, enter the text you want displayed.

For formatting information, see Supported Markdown commands.
Options: Use the fields in the Display pane to customize your content.
To apply your changes to the dashboard, in the toolbar, click Apply. To discard your changes, click Cancel.
To save your modified dashboard, in the toolbar, click Save.

Supported Markdown commands

This section describes the Markdown commands that are supported by the text widget:

Headers

A line starting with a hash, #, indicates a header. You can use multiple hash signs for different levels of headers. For example, for a top-level header use a single hash, # Header. For a second-level header, use two hashs, ## Second-level header.
Fonts
- Italic: Use *italic* or _italic_.
- Bold: Use **bold** or __bold__.
Links: Format as [link text](path).

You can use any value for the link text. The value for path must reference an HTML anchor in the dashboard or be a URL to an external page.
- To link to another section in the dashboard. The anchor for a section is the section title, converted to lowercase with words separated by a hyphen. For example, For example, to link to a section with the title "Charts using variables", set the path to #charts-using-variables.
- To link to an external resource, set path to the URL. For example, to link to example.com, set path to https://example.com/.
Variables: Format as ${VARIABLE_NAME}.

The text widget renders only the value or values of the variable. For example, if you have a label-based variable where the key is zone and the value is us-west1, then the text widget displays us-west1.

When the value of a variable is the wildcard (*), the text widget displays all.

Unrecognized variables are displayed as written and aren't rendered.

Organize dashboard widgets

Custom dashboards let you specify the position of the charts, alerting policies, and other widgets. However, you can improve the usability of a dashboard that has many widgets by creating sections in your dashboard or by grouping widgets:

To create indexed sections in your dashboard, use the section-header widget. When you add this widget to your dashboard, a table of contents is created and a horizontal divider is added to the dashboard. The table of contents lets you navigate to a specific section of the dashboard. Each section widget contains an anchor. When you are troubleshooting, you might want to share the section URL with a teammate. To copy the section URL, right-click Link to heading, and then select Copy link address.
To reduce the time to load a dashboard, use collapsible group widgets and single-view widgets. Both of these widget contain a collection of widgets, and they improve performance by using a lower priority data to retrieve for collection members that aren't displayed. The collapsible group widget displays every member of the collection when it is expanded, otherwise all members are hidden. In contrast, a single-view group widget displays only one member of the collection of at a time, and you use a menu to select which member is displayed.

To use the widgets described in this section, your custom dashboard must use mosaic mode, which is the default layout. If you change the layout to that of a grid, then these widgets aren't available.

The remainder of this section describes how to add and configure widgets that you can use to organize your dashboards. For information about modifying these widgets, see Modify a widget's configuration.

Add a section-header widget

For information about using the Cloud Monitoring API to create a section-header widget, see Dashboard with a SectionHeader widget.

To add a section-header widget by using the Google Cloud console, do the following:

In the Google Cloud console, go to the Dashboards page:
Go to Dashboards

If you use the search bar to find this page, then select the result whose subheading is Monitoring.
In the Add widget dialog, go to the Layout section, and then select Section header widget.
On the widget, click Edit section, and complete the dialog:
- The value of the Section name field is displayed in the table of contents.
- The value for the Subheading field is displayed on the dashboard.
- If you select *Add a divider to the Table of Contents, then a horizontal line is added after the entry in the table of contents.

Add a collapsible group widget

For information about using the Cloud Monitoring API to create a collapsible group widget, see Dashboard with a CollapsibleGroup widget.

To add a collapsible group widget by using the Google Cloud console, do the following:

In the Google Cloud console, go to the Dashboards page:
Go to Dashboards

If you use the search bar to find this page, then select the result whose subheading is Monitoring.
In the Add widget dialog, go to the Layout section, and then select Collapsible Group.
To add a widget to the group, drag the widget to the group.

After you add widgets to the group, you can use your pointer to resize and reposition those widgets.
To add a descriptive title to the group, place your pointer on the widget to activate the toolbar, and then click Edit group.
Optional: To ensure the group is collapsed by default, place your pointer on the widget to activate the toolbar, and then click Collapse group.

When a collapsible group widget is collapsed, Monitoring retrieves the data for the widgets in the group at a lower priority than for other widgets. As a result, your dashboard loads more quickly.

Add a single-view group widget

For information about using the Cloud Monitoring API to create a single-view widget, see Dashboard with a SingleViewGroup widget.

To add a single-view group widget by using the Google Cloud console, do the following:

In the Google Cloud console, go to the Dashboards page:
Go to Dashboards

If you use the search bar to find this page, then select the result whose subheading is Monitoring.
If necessary, create the widgets that you want to add to the single-view widget.
In the Add widget dialog, go to the Layout section, and then select Single View Group.

A single-view group widget is added to your dashboard.
Add widgets to the single-view group widget:
1. In the single-view group widget, expand the Widget menu, and then select Edit group.
2. Click Add widget, and then make a selection from the Add Widget menu.
  
  Note: Not all widget types can be added to a single-view group widget. The Add Widget menu only lists compatible widgets.
3. Repeat the previous step for each widget that you want to add to the single-view group widget.
4. Use the Lower and Higher buttons to order the widgets in the group widget.
5. Click Submit.
The dashboard is refreshed and only one of the widgets that were added to the single-view group widget is visible. The toolbar for the displayed widget lets you edit the displayed widget or perform other actions.

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: