Cloud Monitoring provides an importer that you can use to import dashboard files in the Grafana JSON format into Cloud Monitoring. This document describes how to use the importer to convert Grafana dashboards and optionally upload them to your Google Cloud project.
You can use the importer 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.
The importer 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 a Grafana dashboard uses features that are not available in Cloud Monitoring dashboards, then those aspects of the Grafana dashboard are not converted. These differences are listed in the conversion output. The importer is only designed to handle 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.
Before you begin
Before you can install and run the dashboard importer, you must do the following:
- Use an environment that supports Bash shell scripts.
- Have or install Git.
- Have or install Node.js, version 20.4.1 or newer.
- 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:
Clone the repository:
git clone https://github.com/GoogleCloudPlatform/monitoring-dashboard-samples
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. Theimport.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:
- Converts dashboards in
PATH_TO_DIRECTORY_OR_FILE
from the JSON format used by Grafana into the JSON format used by Cloud Monitoring. 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 theimport.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 theGRAFANA_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_IDWhen 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_IDWhen 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
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
- Create and manage custom dashboards
- View the source code and
README
file for the dashboard importer - Migrate alerting rules and receivers from Prometheus
- View and manage metric usage