importa le dashboard di Grafana in Cloud Monitoring

Cloud Monitoring mette a disposizione un importatore che puoi utilizzare per importare i file delle dashboard in formato JSON Grafana in Cloud Monitoring. Questo documento descrive come utilizzare l'importatore per convertire le dashboard di Grafana e, facoltativamente, caricarle nel tuo progetto Google Cloud.

Puoi utilizzare l'importatore per convertire le dashboard di Grafana e caricarle su Cloud Monitoring come singola operazione oppure puoi eseguire separatamente i passaggi di conversione e caricamento. Con questo approccio, puoi modificare le dashboard convertite prima di caricarle.

L'importatore converte i file della dashboard nel formato JSON utilizzato da Grafana nel formato JSON utilizzato da Cloud Monitoring. Una dashboard convertita potrebbe essere diversa dalla dashboard originale di Grafana. Se una dashboard Grafana utilizza funzionalità non disponibili nelle dashboard di Cloud Monitoring, questi aspetti della dashboard Grafana non vengono convertiti. Queste differenze sono elencate nell'output di conversione. L'importatore è progettato solo per gestire le dashboard che utilizzano espressioni PromQL e origini dati Prometheus. Le dashboard che utilizzano altre forme di query o origini dati potrebbero non essere importate correttamente.

Per informazioni sull'importazione degli avvisi di Prometheus in Cloud Monitoring, consulta Eseguire la migrazione delle regole di avviso e dei ricevitori da Prometheus.

Prima di iniziare

Prima di poter installare ed eseguire l'importatore di dashboard, devi eseguire le seguenti operazioni:

Utilizza un ambiente che supporti gli script shell Bash.
Avere o installare Git.
Avere o installare Node.js, versione 20.4.1 o successiva.
Avere o installare Google Cloud CLI. Se hai già installato gcloud CLI, assicurati di avere la versione più recente eseguendo il comando gcloud components update.

Ottieni l'importatore della dashboard

L'importatore della dashboard è archiviato nel monitoring-dashboard-samples repository di GitHub. Per recuperare l'importatore:

Clona il repository:

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

Passa alla directory per l'importatore della dashboard:

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

L'importatore di dashboard include i seguenti script:

import.sh, che converte le dashboard e, facoltativamente, carica le dashboard convertite in Cloud Monitoring.
upload.sh, che carica le dashboard convertite, o qualsiasi dashboard di Monitoring, in Cloud Monitoring. Lo script import.sh chiama questo script per eseguire il caricamento.

Quando utilizzi lo script import.sh, devi specificare la posizione delle dashboard di Grafana da convertire. L'importatore crea una directory contenente le dashboard convertite e altre informazioni. Le sezioni seguenti descrivono queste directory.

Dashboard di Grafana per la conversione

Puoi utilizzare l'importatore di dashboard per convertire una o più dashboard alla volta specificando un percorso ai file delle dashboard.

Puoi specificare il percorso di una directory che contiene le dashboard. Vengono elaborati solo i file nella directory con l'estensione .json.
Puoi specificare il percorso di un singolo file JSON. Il nome del file deve avere l'estensione .json.

Dashboard convertite e altre informazioni

Quando l'importatore viene eseguito per la prima volta, crea una sottodirectory reports. Ogni volta che esegui l'importatore, visualizzerai una nuova directory di output nella directory reports, denominata in base alla data e all'ora. Il nome della directory di output ha la seguente struttura:
reports/YYYY-M-D/HH:MM:SS

Per ogni chiamata all'importatore, la directory di output contiene quanto segue:

Uno o più file con gli stessi nomi delle dashboard originali di Grafana, ma ora in formato JSON Cloud Monitoring.
Un file report.json, che registra le seguenti informazioni per ogni dashboard convertita:
- Il nome e la posizione del file della dashboard Grafana convertito.
- Il nome e la posizione del file della dashboard di Monitoring convertito.
- Avvisi sulle funzionalità della dashboard Grafana che non dispongono di funzionalità corrispondenti in Cloud Monitoring e che pertanto non possono essere incluse nella dashboard convertita.
- Eventuali errori che si sono verificati nella conversione.

Se hai caricato le dashboard, la directory dei report include anche un file upload_HH:MM:SS.txt, che include l'URL in cui è stata caricata la dashboard.

Importa dashboard Grafana

Per convertire le dashboard di Grafana e caricarle su Cloud Monitoring, utilizza lo script import.sh:

./import.sh PATH_TO_DIRECTORY_OR_FILE PROJECT_ID

Questo script svolge le seguenti operazioni:

Converte le dashboard in PATH_TO_DIRECTORY_OR_FILE dal formato JSON utilizzato da Grafana al formato JSON utilizzato da Cloud Monitoring.
Carica le dashboard convertite nel progetto Google Cloud PROJECT_ID utilizzando Google Cloud CLI.

Se non hai eseguito l'autenticazione a gcloud CLI, esegui il comando gcloud auth login prima di eseguire lo script import.sh.

Puoi importare tutte le dashboard di Grafana in una directory oppure specificarne una sola da importare.

Per importare tutte le dashboard della directory GRAFANA_DASHBOARDS_DIR nel progetto Google Cloud PROJECT_ID, specifica la directory relativa alla directory dell'importatore e l'ID del progetto di destinazione quando richiami lo script:
```
./import.sh GRAFANA_DASHBOARDS_DIR PROJECT_ID
```
Per convertire solo la dashboard MY_GRAFANA_DASHBOARD.json nella directory GRAFANA_DASHBOARDS_DIR, includi il nome file della dashboard, relativo alla directory dell'importatore, quando richiami lo script:
```
./import.sh GRAFANA_DASHBOARDS_DIR/MY_GRAFANA_DASHBOARD.json PROJECT_ID
```

L'importatore della dashboard include una dashboard Grafana di esempio come examples/k8s_cluster_example.json. Il comando seguente importa la dashboard nel progetto specificato:

./import.sh examples/k8s_cluster_example.json PROJECT_ID

Quando viene richiamato con PROJECT_ID my-project-test-1, l'output è simile al seguente:

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

Dopo che lo script import.sh ha creato la directory di output e convertito le dashboard, ma prima di caricare le dashboard convertite nel progetto, ti chiede di confermare. Se inserisci y, lo script caricherà la dashboard e visualizzerà l'URL della nuova 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

Converti le dashboard di Grafana senza caricarle

Se vuoi ispezionare o modificare le dashboard convertite prima di caricarle, ometti il valore PROJECT_ID quando richiami lo script import.sh:

./import.sh PATH_TO_DIRECTORY_OR_FILE

L'importatore converte le dashboard come descritto in Importare le dashboard di Grafana, ma non carica le dashboard convertite in Cloud Monitoring.

Puoi eseguire il passaggio di caricamento in un secondo momento utilizzando lo script upload.sh manualmente.

Carica manualmente le dashboard

Per caricare manualmente le dashboard in formato JSON di Cloud Monitoring, utilizza lo script upload.sh.

    ./upload.sh PATH_TO_DIRECTORY_OR_FILE PROJECT_ID

Lo script upload.sh utilizza Google Cloud CLI per caricare i file JSON. Se non hai eseguito l'autenticazione all'interfaccia alla gcloud CLI, esegui il comando gcloud auth login prima di eseguire lo script upload.sh.

Per caricare tutte le dashboard in una directory reports/YYYY-M-D/HH:MM:SS, specifica la directory relativa alla directory dell'importatore e l'ID progetto di destinazione quando richiami lo script:
```
./upload.sh reports/YYYY-M-D/HH:MM:SS PROJECT_ID
```
Durante il caricamento di tutte le dashboard da una directory, lo script ti chiede di continuare o di uscire prima di caricare le dashboard.
Per caricare una dashboard specifica in una directory reports/YYYY-M-D/HH:MM:SS, specifica la directory e il nome file in relazione alla directory dell'importatore e l'ID progetto di destinazione quando richiami lo script:
```
./upload.sh reports/YYYY-M-D/HH:MM:SS/MY_MONITORING_DASHBOARD.json PROJECT_ID
```
Quando carichi una singola dashboard da una directory, lo script viene eseguito senza avvisarti prima di caricare le dashboard.

Ad esempio, il seguente comando carica una dashboard archiviata in una sottodirectory reports nel progetto Google Cloud 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

Risoluzione dei problemi

A volte pubblichiamo piccoli aggiornamenti e correzioni di bug allo strumento. Prima di tentare ulteriori procedure di risoluzione, prova a risolverlo utilizzando git pull per scaricare l'ultima versione del repository, quindi esegui di nuovo l'importazione.

Per informazioni sui problemi relativi alle dashboard convertite, ad esempio grafici che non mostrano dati, vedi il file README dell'importatore.

Passaggi successivi

Creare e gestire dashboard personalizzate
Visualizza il codice sorgente e il file README per l'importatore della dashboard
Eseguire la migrazione delle regole di avviso e dei ricevitori da Prometheus
Visualizzare e gestire l'utilizzo delle metriche