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

• Byusing the Google Cloud console.
• Byusing the importer tool.

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

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

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

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

Before you begin

Whether you use the Google Cloud console or the importer tool to importyour dashboards, you must have sufficientauthorization, and youneeddashboards to import. When using the importertool, there areadditional prerequisites.

Authorization

To get the permissions that you need to create and modify custom dashboards, ask your administrator to grant you theMonitoring Editor (roles/monitoring.editor) IAM role on your project. For more information about granting roles, seeManage access to projects, folders, and organizations.

You might also be able to get the required permissions throughcustom roles or otherpredefined roles.

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

Collect the Grafana dashboards to import

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

Import dashboards by using the Google Cloud console

You can import Grafana dashboards into Cloud Monitoring from theMonitoringDashboards page in the Google Cloud console.

Import Grafana dashboards

To import one or more Grafana dashboards, do the following

1. In the Google Cloud console, go to thedashboard Dashboards page:

   Go toDashboards

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

2. In the toolbar of the Google Cloud console,select your Google Cloud project. ForApp Hubconfigurations, select the App Hub host project or management project.

3. ClickImport Dashboard.

4. ClickBrowse to navigate to the directory where you have stored yourGrafana dashboards in JSON format, and select the dashboards you want toimport.

   Each JSON file is staged after it is selected; theStaged Filespane indicates whether there are any issues in the conversion.

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

5. Clicksave_alt Import. TheImport results pane indicates whether ornot each dashboard has been successfully imported.

6. To view a successfully imported dashboard, clickopen_in_new View.

View your imported dashboards

To view your imported dashboards, do the following:

1. In the Google Cloud console, go to thedashboard Dashboards page:

   Go toDashboards

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

2. In the toolbar of the Google Cloud console,select your Google Cloud project. ForApp Hubconfigurations, select the App Hub host project or management project.

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

   • In theType menu, selectCustom.

   • In theLabels pan, select thecloud-monitoring-dashboard-importer label to see onlyGrafana dashboards imported by using the Google Cloud console.

     Note: You can also create your own labels and add them to customdashboards, like Grafana dashboards that you import. Labels can helpyou manage your dashboards. For example, you might add the labelprodto dashboards that display information about production systems.

   • Use the filter bar search by name.

Add or remove user-defined labels

You can add labels only to custom dashboards, which include dashboards thatyou import. When a dashboard displays thesellAdd labels to dashboard button, then you canconfigure which labels are applied to the dashboard.

To add or remove user-defined labels to a dashboard, do the following:

1. In the Google Cloud console, go to thedashboard Dashboards page:

   Go toDashboards

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

2. In the list of dashboards, locate the dashboard and then clicksellAdd labels to dashboard.
3. Do one of the following:

   • To create a label and add it to your dashboard, in theCreate a new label section, enter the name of the label in the textbox and then clickCreate and apply.

   • To configure which labels are added to your dashboard, clickarrow_drop_downSelect labels to apply, select the labels, and then clickOk.
4. To save your changes, clickConfirm.

Import dashboards by using the importer tool

You can use the importer tool to convert Grafana dashboards and upload themto Cloud Monitoring as a single operation, or you can perform theconversion and upload steps separately. You might choose this approach if youwant 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 supportsBash shellscripts.
2. Have orinstall Git.
3. Have orinstall Node.js, version 20.4.1 ornewer.
4. Have orinstall the Google Cloud CLI. If you already havethe gcloud CLI installed, ensure that you have the latestversion by running thegcloud components updatecommand.

Obtain the dashboard importer

The dashboard importer is stored in themonitoring-dashboard-samplesGitHub repository.To obtain and set up 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

3. Install the node modules and build the files

   npm install && npm run build

The dashboard importer includes the following scripts:

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

• upload.sh, which uploads the converteddashboards—or any Monitoring dashboards—toCloud Monitoring. Theimport.sh script calls thisscript to do the upload.

When you use theimport.sh script, you must specify thelocation of the Grafana dashboards to convert. The importer creates adirectory 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 ata 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 havethe.json extension.

Converted dashboards and other information

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

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

• A file or files with the same names as the original Grafana dashboards, butnow in Cloud Monitoring JSON format.
• Areport.json file, which records the following informationfor each converted dashboard:
  • The name and location of the Grafana dashboard file that was converted.
  • The name and location of the converted Monitoring dashboardfile.
  • Notices about any features in the Grafana dashboard that have nocorresponding feature in Cloud Monitoring and therefore couldn'tbe included in the converted dashboard.
  • Any errors that occurred in the conversion.

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

Import Grafana dashboards

To convert Grafana dashboards and upload them to Cloud Monitoring, usetheimport.sh script:

./import.shPATH_TO_DIRECTORY_OR_FILEPROJECT_ID

This script does the following:

1. Converts dashboards inPATH_TO_DIRECTORY_OR_FILE from the JSON formatused by Grafana into the JSON format used by Cloud Monitoring.

2. Uploads the converted dashboards into your Google Cloud projectPROJECT_IDby using the Google Cloud CLI.

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

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

• To import all the dashboards in theGRAFANA_DASHBOARDS_DIR directoryinto thePROJECT_ID Google Cloud project,specify the directory, relative to the importer directory, and thedestination project ID when invoking the script:

  ./import.shGRAFANA_DASHBOARDS_DIRPROJECT_ID

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

  ./import.shGRAFANA_DASHBOARDS_DIR/MY_GRAFANA_DASHBOARD.jsonPROJECT_ID

The dashboard importer includes a sample Grafana dashboard asexamples/k8s_cluster_example.json. The following command importsthat dashboard into the specified project:

./import.sh examples/k8s_cluster_example.jsonPROJECT_ID

When invoked with thePROJECT_IDmy-project-test-1, the output resemblesthe following:

Converting: Kubernetes Cluster Overview✓ Kubernetes Cluster Overview converted successfullyConversion of examples/k8s_cluster_example.json complete. Conversion Report located at: reports/2023-9-28/22:14:57/report.jsonTo 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-1Uploading 1 dashboard(s) from a directory with the following args:Directory: reports/2023-9-28/22:14:57/Project: my-project-test-1The following are your dashboards:- k8s_cluster_example.json

After theimport.sh script has created the output directoryand converted the dashboards, but before it uploads the converted dashboardsto your project, it prompts you for confirmation. Entery, and the scriptuploads 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-1Upload log created in reports/2023-9-28/22:14:57/upload_22:14:57.txtNeed 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 uploadingthem, then omit thePROJECT_ID value when invoking theimport.sh script:

./import.shPATH_TO_DIRECTORY_OR_FILE

The importer converts the dashboards as described inImport Grafana dashboardsbut does not upload the converted dashboards to Cloud Monitoring.

You can run the upload step later, by using theupload.shscript manually.

Upload dashboards manually

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

    ./upload.shPATH_TO_DIRECTORY_OR_FILEPROJECT_ID

Theupload.sh script uses the Google Cloud CLIto upload the JSON files. If you have not authenticated to thegcloud CLI, then run thegcloud auth logincommand before running theupload.sh script.

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

  ./upload.shreports/YYYY-M-D/HH:MM:SSPROJECT_ID

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

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

  ./upload.shreports/YYYY-M-D/HH:MM:SS/MY_MONITORING_DASHBOARD.jsonPROJECT_ID

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

For example, the following command uploads a dashboard storedin areports subdirectory to the Google Cloud projectmy-project-test-1:

./upload.sh reports/2023-9-26/22:48:31/k8s_cluster_example.json my-project-test-1Uploading 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 thedashboard Dashboards page:

   Go toDashboards

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

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

   • Select theCustom category to see only user-defined dashboards.
   • Select thecloud-ops-grafana-importer label to see only Grafanadashboards 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. Beforeattempting further troubleshooting, first try fixing the issue byusinggit pull to pull down the latestversion of the repository and then importing again.

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

What's next

• Create and manage custom dashboards
• Migrate alerting rules and receivers from Prometheus
• View and manage metric usage