Manage custom dashboards

This document describes how to create and manage custom dashboards by using the Google Cloud console. Custom dashboards let you display information that is of interest to you, organized in a way that's useful to you. For example, you might create a dashboard to display the logs, performance metrics, and alerting policies for virtual machines (VM) in your production environment. After you create a custom dashboard, you can also copy, modify, and share it. To create custom dashboards, you can use the Google Cloud console, the Cloud Monitoring API, or the Google Cloud CLI.

Custom dashboards support a variety of widget types, so that you can choose the best way to display your metric data. These dashboards also let you display metric data from multiple Google Cloud projects and metrics from multiple Google Cloud services. In addition to metrics, custom dashboards can display log entries from multiple Google Cloud projects and alerting policies, and you can create template variables to filter your dashboard.

This document describes how to create and manage your custom dashboards by using the Google Cloud console:

For information about how to manage custom dashboards by using the API and the Google Cloud CLI, see Manage dashboards by API.
For information about service-specific Google Cloud dashboards, see View Google Cloud dashboards.

Before you begin

Ensure that your Identity and Access Management role includes the necessary permissions:

To get the permissions that you need to view dashboards, ask your administrator to grant you the role of Monitoring Viewer (roles/monitoring.viewer).
To get the permissions that you need to create and edit dashboards, and to edit dashboards, ask your administrator to grant you the role of Monitoring Editor (roles/monitoring.editor).

For more information about roles, see Access control.

Create a custom dashboard

In the Google Cloud console, select Monitoring or click the following button:
Go to Monitoring
In the navigation pane, select Dashboards.
In the Dashboards Overview page, click Create dashboard.
For each widget that you want to add to the dashboard, do the following:
1. Select a widget from the Chart library, or drag one from the library to the graph area.
  
  A preconfigured widget of the selected type is displayed. The following example illustrates a Line chart and its configuration pane:
2. To change the time series shown by the widget, select the type configuration that you want to do, and then complete the form. For example, to minimize the number of fields that you need to complete, select the Basic tab, and then use the menus on that tab to configure the widget. For information about your choices, see Add dashboard widgets.

View a custom dashboard

Custom dashboards are displayed in the same list as the service-specific dashboards that Cloud Monitoring creates as you add resources to your Google Cloud project.

To view a custom dashboard, do the following:

In the Google Cloud console, select Monitoring or click the following button:
Go to Monitoring
In the navigation pane, select Dashboards.
Select the dashboard name. You can restrict the list to only custom dashboards by adding the filter Type: Custom.
If the Close editor button is shown, then click it.
Optional: Add or modify the dashboard filters to temporarily change the time series shown by the dashboard widgets. For more information, see Filter a dashboard.
Optional: Change the display period for all widgets on the dashboard. By default, the time-range selector is set to one hour.

To change the displayed time range, use the time-range selector. For example, if you want to view the data for the past week, then select Last 1 week from the time-range selector. You can also specify a start and end time, or specify a time to view around.

For dashboards that display sparse data, such as quota metrics, set the time-range selector to at least one week.
Optional: Change the configuration for every widget on a dashboard by using the dashboard's Settings options. These options let you, for example, show or hide legends.

Modify a custom dashboard

Modify a dashboard when you want to add or remove widgets, change the layout of the dashboard widgets, change a widget's type, or change the time series shown by a widget.

To modify a custom dashboard, do the following:

In the Google Cloud console, select Monitoring or click the following button:
Go to Monitoring
In the navigation pane, select Dashboards, then select the dashboard that you want to view or edit.
If the Edit dashboard button is shown, then click it.
Modify the dashboard by doing any of the following:
- To add a widget, click Add chart, select the widget of interest, and complete the dialog. For more information, see Add dashboard widgets.
- To modify the time series shown by an existing widget, select that widget and then make your changes by using the widget's configuration pane. For information about how to configure a widget, see Add dashboard widgets.
- To modify a widget or the dashboard by editing the JSON representation, click JSON editor. After your changes are complete, click Apply changes in the editor's toolbar.
  
  When you open the JSON editor after selecting a widget, the JSON editor expands only that widget's representation. To view the entire dashboard definition, in the JSON editor select Show more:
- To change a widget's type, click the name of the current widget and then make a selection from the menu. For example, to change a line chart to a stacked area chart, click Line chart and select Stacked area chart from the menu. For more information, see Change a widget's type.
- To delete a widget, click Delete in the widget's toolbar.
- To resize or reposition a widget, use your pointer. These options are disabled when a dashboard is in grid mode.
- To change the layout of widgets on the dashboard, use the Grid and Mosaic toggle. When you select Grid, all widgets have the same dimensions.

Delete a custom dashboard

Deleting a dashboard that contains alert charts doesn't delete the alerting policies whose data was displayed on those alert charts. Therefore, you might receive notifications from those policies after the dashboard is deleted. For information about how to manage your policies, which you do from the Alerting page in the Google Cloud console, see Manage policies.

To delete a custom dashboard, do the following:

In the Google Cloud console, select Monitoring or click the following button:
Go to Monitoring
In the navigation pane, select Dashboards.
To begin the delete action, find the dashboard you want to delete and click Delete.
In the confirmation dialog, click Delete

Duplicate a custom dashboard within the same project

When you want to experiment with different metrics or different aggregation options, one option is to duplicate a dashboard and use the copy for experimentation purposes.

To duplicate a dashboard, do the following:

In the Google Cloud console, select Monitoring or click the following button:
Go to Monitoring
In the navigation pane, select Dashboards.
In the Dashboards Overview page, identify the dashboard to copy, and then click Copy.
Click Copy in the confirmation dialog.

Copy a custom dashboard to another project

When you have multiple Cloud projects and you want them to have the same custom dashboard, you can create the dashboard in one project and then copy it to other projects. The copy has the same layout and properties as the source dashboard; however, the data the copy displays is different.

To copy a dashboard from one project to another, your IAM role for the destination Cloud projects must include the Monitoring editor permission. For more information about roles, see Access control.

To copy a dashboard definition to another Cloud project, do the following:

In the Google Cloud console, select Monitoring or click the following button:
Go to Monitoring
In the navigation pane, select Dashboards, then select the dashboard that you want to view or edit.
Copy the dashboard definition to your clipboard:
1. If the Edit dashboard button is shown, then click it.
2. In the dashboard toolbar, click JSON editor to open the JSON editor.
3. In the editor's toolbar, click Copy.
Paste the definition into a new dashboard created in a different project:
1. Use the Google Cloud console project picker to select the project where you want to save the dashboard definition.
2. Click Create dashboard.
3. In the dashboard toolbar, click JSON editor to open the JSON editor.
4. Paste the content of your clipboard into the editor.
5. Click Apply changes.

When you are investigating a data anomaly, you might want another individual in your team or your organization to view the same data that you are viewing. For example, you might see an unexpected drop, or spike, in a performance metric and you want to consult with a teammate. In this scenario, you want your teammate to view the dashboard and its data.

For information about how share a link to a dashboard, see Share dashboards.

Share a custom dashboard definition

You might have created a custom dashboard that others in your team or organization want to install in their projects. When you want to share a dashboard definition, save it to your local system, and then move or copy the definition to a shared location. For example, you might copy the definition to a shared drive or to a source code repository like GitHub. Any individual with access to the stored location can install the dashboard into their Cloud projects.

To save the definition of a custom dashboard to a JSON-formatted file that is stored on your local system, do the following:

In the Google Cloud console, select Monitoring or click the following button:
Go to Monitoring
In the navigation pane, select Dashboards, then select the dashboard that you want to view or edit.
If the Edit dashboard button is shown, then click it.
In the dashboard toolbar, click JSON editor to open the JSON editor.
To save the dashboard definition to a local system, click File download:

The created file, named for the dashboard, contains a JSON representation of the dashboard. This file only stores the definition of the dashboard, it doesn't store time-series data.

Install a custom dashboard definition

To use or customize a dashboard that someone else created, install that dashboard's definition in your Cloud project. Cloud Monitoring, for example, provides a curated set of dashboard definitions on GitHub that are specific to various Google Cloud services. The charts on these dashboards present a selection of metrics relevant to a specific service. You can install these definitions in your Cloud project as custom dashboards and then modify them to show the data you want to view.

For information about how to install a dashboard by using the Cloud Monitoring API or the Google Cloud CLI, see Install sample dashboards.

To install a dashboard definition by using the Google Cloud console, do the following:

In the Google Cloud console, select Monitoring or click the following button:
Go to Monitoring
In the navigation pane, select Dashboards, and then do one of the following:
- To install a dashboard from the sample library, do the following:
  1. Click the Sample library tab.
  2. Select the dashboards that you want to install.
  3. (Optional) To view details about a dashboard or to preview its contents, click Preview.
  4. (Optional) To view the JSON representation of a dashboard, click Preview and then JSON.
  5. Click Import.
- To install a dashboard by uploading a JSON file, do the following:
  1. (Optional) To install a curated dashboard definition, download the GitHub repository:
```
git clone https://github.com/GoogleCloudPlatform/monitoring-dashboard-samples.git
```
    Note: Some of the dashboards definitions stored in the GitHub repository display custom metric data. To install these dashboards successfully, you must create the necessary custom metrics. For more information, consult the per-service documentation in the repository.
  2. Click Create dashboard.
  3. In the dashboard toolbar, click JSON editor.
    
    For a new dashboard, the displayed code is similar to the following:
```
{
  "category": "CUSTOM",
  "displayName": "New Dashboard",
  "mosaicLayout": {
    "columns": 12
  },
}
```
  4. In the editor's toolbar, click File Upload.
  5. Select the file that contains the dashboard definition and then click Open.
    
    After the file is uploaded, the dashboard's JSON is updated.
    
    If you see the following message, "Unable to save dashboard: Field mosaicLayout.tiles[0] has an invalid value", then select Grid in the dashboard toolbar.
  6. (Optional) Customize the dashboard. For example, you can update the title, add a text box that indicates the dashboard source, delete unwanted charts, or add charts.

Disable data refresh

When you see a data anomaly shown by a chart, you might want to preserve the current view while you investigate the anomaly. By default, dashboards automatically refresh the display as new data is available.

To stop the automatic refresh of the dashboard, click the auto refresh toggle until it displays Off.

To enable the automatic refresh of the dashboard, click the auto refresh toggle until it displays On.

Disable automatic saving of configuration changes

By default, dashboards are configured to save your changes as you make them. However, when you want to experiment or when you want to configure a dashboard by editing the JSON representation, you might want to use a manual process to save your changes.

To manually save changes that you make, do the following:

Click the Autosave toggle until the Save button is shown.
Make your modifications to the dashboard.
To keep your changes, click Save.

To enable automatic saving of your configuration changes, ensure the Autosave toggle is in the on position. When Cloud done is displayed, your changes have been saved.