Import Grafana dashboards into Cloud Monitoring

This document describes how to import dashboard files in the Grafana JSON format into Cloud Monitoring. You can import Grafana dashboards in the following ways:

The import process converts dashboard files in the JSON format used by Grafana into the JSON format used by Cloud Monitoring. A converted dashboard might differ from the original Grafana dashboard. If, for example, a Grafana dashboard uses features that aren't available in Cloud Monitoring dashboards, then those aspects of the Grafana dashboard are not converted. These differences are listed in the results of the import.

You can only import dashboards that use PromQL expressions and Prometheus data sources. Dashboards that use other forms of querying or data sources might not import successfully.

For information about importing Prometheus alerts into Cloud Monitoring, see Migrate alerting rules and receivers from Prometheus.

For general information about managing your imported dashboards, see Create and manage custom dashboards.

Before you begin

Whether you use the Google Cloud console or the importer tool to import your dashboards, you must have sufficient authorization, and you need dashboards to import. When using the importer tool, there are additional prerequisites.

Authorization

To get the permissions that you need to create and modify custom dashboards, 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.

Collect the Grafana dashboards to import

To import Grafana dashboards, you must have them stored locally as files in JSON format. You might want to create a directory specifically for these dashboard files.

Import dashboards by using the Google Cloud console

You can import Grafana dashboards into Cloud Monitoring from the following places in the Google Cloud console:

  • The Dashboard list tab on the Monitoring Dashboards page.
  • The dashboard section of the onboarding checklist on the Monitoring Overview page.

Import Grafana dashboards

To import one or more Grafana dashboards, do the following

  1. Go to either the Dashboards or Overview page in Monitoring:

    • 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 Google Cloud console, go to the Monitoring Overview page:

      Go to Overview

      If you use the search bar to find this page, then select the result whose subheading is Monitoring.

  2. Click  Import Grafana Dashboards.

  3. Click Browse to navigate to the directory where you have stored your Grafana dashboards in JSON format, and select the dashboards you want to import.

    Each JSON file is staged after it is selected; the Staged Files pane indicates whether there are any issues in the conversion.

    • Click  View converted JSON to see the results of the conversion.
    • Click  Remove file to remove a dashboard from the import operation.

  4. Click  Import. The Import results pane indicates whether or not each dashboard has been successfully imported.

  5. To view a successfully imported dashboard, click  View.

View your imported dashboards

To view your imported dashboards, do the following:

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

  2. Locate the dashboard that you want to view in the list. To filter the list of dashboards, you can do the following:

    • Select the Custom category to see only user-defined dashboards.
    • Select the cloud-monitoring-dashboard-importer label to see only Grafana dashboards imported by using the Google Cloud console.
    • Use the filter bar search by name.

Import dashboards by using the importer tool

You can use the importer tool to convert Grafana dashboards and upload them to Cloud Monitoring as a single operation, or you can perform the conversion and upload steps separately. You might choose this approach if you want to edit the converted dashboards before uploading them.

Additional prerequisites

Before you can install and run the dashboard importer, you must do the following:

  1. Use an environment that supports Bash shell scripts.
  2. Have or install Git.
  3. Have or install Node.js, version 20.4.1 or newer.
  4. Have or install the Google Cloud CLI. If you already have the gcloud CLI installed, ensure that you have the latest version by running the gcloud components update command.

Obtain the dashboard importer

The dashboard importer is stored in the monitoring-dashboard-samples GitHub repository. To get the importer, do the following:

  1. Clone the repository:

    git clone https://github.com/GoogleCloudPlatform/monitoring-dashboard-samples

  2. Change to the directory for the dashboard importer:

    cd monitoring-dashboard-samples/scripts/dashboard-importer

The dashboard importer includes the following scripts:

  • import.sh, which converts dashboards and optionally uploads the converted dashboards to Cloud Monitoring.

  • upload.sh, which uploads the converted dashboards—or any Monitoring dashboards—to Cloud Monitoring. The import.sh script calls this script to do the upload.

When you use the import.sh script, you must specify the location of the Grafana dashboards to convert. The importer creates a directory that contains the converted dashboards and other information. The following sections describe these directories.

Grafana dashboards to convert

You can use the dashboard importer to convert one or more dashboards at a time by specifying a path to the dashboards files.

  • You can specify the path to a directory that contains dashboards. Only files in the directory that have the .json extension are processed.

  • You can specify the path to a single JSON file. The filename must have the .json extension.

Converted dashboards and other information

When the importer runs the first time, it creates a reports subdirectory. Every time you run the importer, you get a new output directory under the reports directory, named by the date and time. The name of the output directory has the following structure:
reports/YYYY-M-D/HH:MM:SS

For each invocation of the importer, the output directory contains the following:

  • A file or files with the same names as the original Grafana dashboards, but now in Cloud Monitoring JSON format.
  • A report.json file, which records the following information for each converted dashboard:
    • The name and location of the Grafana dashboard file that was converted.
    • The name and location of the converted Monitoring dashboard file.
    • Notices about any features in the Grafana dashboard that have no corresponding feature in Cloud Monitoring and therefore couldn't be included in the converted dashboard.
    • Any errors that occurred in the conversion.

If you have uploaded the dashboards, the report directory also includes an upload_HH:MM:SS.txt file, which includes the URL to which the dashboard was uploaded.

Import Grafana dashboards

To convert Grafana dashboards and upload them to Cloud Monitoring, use the import.sh script:

./import.sh PATH_TO_DIRECTORY_OR_FILE PROJECT_ID

This script does the following:

  1. Converts dashboards in PATH_TO_DIRECTORY_OR_FILE from the JSON format used by Grafana into the JSON format used by Cloud Monitoring.

  2. Uploads the converted dashboards into your Google Cloud project PROJECT_ID by using the Google Cloud CLI.

    If you have not authenticated to the gcloud CLI, then run the gcloud auth login command before running the import.sh script.

You can import all the Grafana dashboards in a directory, or you can specify a single dashboard in the directory to import.

  • To import all the dashboards in the GRAFANA_DASHBOARDS_DIR directory into the PROJECT_ID Google Cloud project, specify the directory, relative to the importer directory, and the destination project ID when invoking the script:

    ./import.sh GRAFANA_DASHBOARDS_DIR PROJECT_ID

  • To convert only the MY_GRAFANA_DASHBOARD.json dashboard in the GRAFANA_DASHBOARDS_DIR directory, include the dashboard filename, relative to the importer directory, when invoking the script:

    ./import.sh GRAFANA_DASHBOARDS_DIR/MY_GRAFANA_DASHBOARD.json PROJECT_ID

The dashboard importer includes a sample Grafana dashboard as examples/k8s_cluster_example.json. The following command imports that dashboard into the specified project:

./import.sh examples/k8s_cluster_example.json PROJECT_ID

When invoked with the PROJECT_ID my-project-test-1, the output resembles the following:

Converting: Kubernetes Cluster Overview
✓ Kubernetes Cluster Overview converted successfully

Conversion of examples/k8s_cluster_example.json complete. Conversion Report located at: reports/2023-9-28/22:14:57/report.json


To upload these dashboard(s) manually, you can run:
./upload.sh reports/2023-9-28/22:14:57/ <PROJECT_ID>

Conversion Complete. Proceeding to uploading...

Now running: ./upload.sh reports/2023-9-28/22:14:57/ my-project-test-1

Uploading 1 dashboard(s) from a directory with the following args:
Directory: reports/2023-9-28/22:14:57/
Project: my-project-test-1

The following are your dashboards:
- k8s_cluster_example.json

After the import.sh script has created the output directory and converted the dashboards, but before it uploads the converted dashboards to your project, it prompts you for confirmation. Enter y, and the script uploads the dashboard and prints the URL for the new dashboard:

Would you like to continue? (y/n) y

✓ k8s_cluster_example.json successfully uploaded:
https://console.cloud.google.com/monitoring/dashboards/builder/9c341ef8-cfef-4bdd-98d5-821571c520ef?project=my-project-test-1

Upload log created in reports/2023-9-28/22:14:57/upload_22:14:57.txt

Need to troubleshoot? Please visit:
https://github.com/GoogleCloudPlatform/monitoring-dashboard-samples/tree/master/scripts/dashboard-importer/README.md#troubleshooting

Convert Grafana dashboards without uploading

If you want to inspect or edit the converted dashboards before uploading them, then omit the PROJECT_ID value when invoking the import.sh script:

./import.sh PATH_TO_DIRECTORY_OR_FILE

The importer converts the dashboards as described in Import Grafana dashboards but does not upload the converted dashboards to Cloud Monitoring.

You can run the upload step later, by using the upload.sh script manually.

Upload dashboards manually

To manually upload dashboards in Cloud Monitoring JSON format, use the upload.sh script.

    ./upload.sh PATH_TO_DIRECTORY_OR_FILE PROJECT_ID

The upload.sh script uses the Google Cloud CLI to upload the JSON files. If you have not authenticated to the gcloud CLI, then run the gcloud auth login command before running the upload.sh script.

  • To upload all the dashboards in a reports/YYYY-M-D/HH:MM:SS directory, specify the directory, relative to the importer directory, and the destination project ID when invoking the script:

    ./upload.sh reports/YYYY-M-D/HH:MM:SS PROJECT_ID

    When uploading all dashboards from a directory, the script prompts you to continue or exit before uploading the dashboards.

  • To upload a specific dashboard in a reports/YYYY-M-D/HH:MM:SS directory, specify the directory and filename, relative to the importer directory, and the destination project ID when invoking the script:

    ./upload.sh reports/YYYY-M-D/HH:MM:SS/MY_MONITORING_DASHBOARD.json PROJECT_ID

    When uploading a single dashboard from a directory, the script runs without prompting you before uploading the dashboards.

For example, the following command uploads a dashboard stored in a reports subdirectory to the Google Cloud project my-project-test-1:

./upload.sh reports/2023-9-26/22:48:31/k8s_cluster_example.json my-project-test-1
Uploading json file: k8s_cluster_example.json to project: my-project-test-1...

✓ k8s_cluster_example.json successfully uploaded:
https://console.cloud.google.com/monitoring/dashboards/builder/25956d9a-93e2-410c-ada1-ec6872cb6665?project=my-project-test-1

View your uploaded dashboards

To view your uploaded dashboards, do the following:

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

  2. Locate the dashboard that you want to view in the list. To filter the list of dashboards, you can do the following:

    • Select the Custom category to see only user-defined dashboards.
    • Select the cloud-ops-grafana-importer label to see only Grafana dashboards imported by using the importer tool.
    • Use the filter bar search by name.

Troubleshooting

We occasionally publish small updates and bug fixes to the tool. Before attempting further troubleshooting, first try fixing the issue by using git pull to pull down the latest version of the repository and then importing again.

For information about problems with the converted dashboards, such as charts not showing data, see the importer's README file.

What's next