Importar painéis do Grafana para o Cloud Monitoring

O Cloud Monitoring fornece um importador que pode ser usado para importar arquivos de painel no formato JSON do Grafana para o Cloud Monitoring. Neste documento, descrevemos como usar o importador para converter os painéis do Grafana e, opcionalmente, fazer upload deles para seu projeto do Google Cloud.

Use o importador para converter os painéis do Grafana e fazer upload deles para o Cloud Monitoring como uma única operação. Também é possível executar as etapas de conversão e upload separadamente. Escolha essa abordagem se quiser editar os painéis convertidos antes de fazer o upload deles.

O importador converte arquivos do painel no formato JSON usado pelo Grafana para o formato JSON usado pelo Cloud Monitoring. Um painel convertido pode ser diferente do painel original do Grafana. Se um painel do Grafana usar recursos que não estão disponíveis nos painéis do Cloud Monitoring, esses aspectos do painel do Grafana não serão convertidos. Essas diferenças estão listadas nos resultados da conversão. O importador foi projetado apenas para processar painéis que usam expressões do PromQL e fontes de dados do Prometheus. Os painéis que usam outras formas de consulta ou fontes de dados podem não ser importados.

Para informações sobre como importar alertas do Prometheus para o Cloud Monitoring, consulte Migrar regras de alerta e receptores do Prometheus.

Antes de começar

Antes de instalar e executar o importador de painel, faça o seguinte:

Use um ambiente compatível com scripts de shell Bash.
Tenha ou instale o Git.
Ter ou instalar o Node.js, versão 20.4.1 ou mais recente.
Ter ou instalar a CLI do Google Cloud. Se você já tiver a CLI gcloud instalada, verifique se tem a versão mais recente executando o comando gcloud components update.

Conseguir o importador do dashboard

O importador do painel é armazenado no repositório monitoring-dashboard-samples do GitHub. Para conseguir o importador, faça o seguinte:

Clone o repositório:

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

Mude para o diretório do importador do dashboard:

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

O importador do painel inclui os seguintes scripts:

import.sh, que converte painéis e, opcionalmente, faz o upload dos painéis convertidos para o Cloud Monitoring.
upload.sh, que faz upload dos painéis convertidos (ou de qualquer painel do Monitoring) para o Cloud Monitoring. O script import.sh o chama para fazer o upload.

Ao usar o script import.sh, especifique o local dos painéis do Grafana que serão convertidos. O importador cria um diretório que contém os painéis convertidos e outras informações. As seções a seguir descrevem esses diretórios.

Painéis do Grafana para conversão

É possível usar o importador de painel para converter um ou mais painéis de uma vez especificando um caminho para os arquivos dos painéis.

É possível especificar o caminho para um diretório que contém dashboards. Somente arquivos no diretório que têm a extensão .json são processados.
Você pode especificar o caminho para um único arquivo JSON. O nome do arquivo precisa ter a extensão .json.

Painéis convertidos e outras informações

Quando o importador é executado pela primeira vez, ele cria um subdiretório reports. Sempre que você executar o importador, receberá um novo diretório de saída no diretório reports, nomeado pela data e hora. O nome do diretório de saída tem a seguinte estrutura:
reports/YYYY-M-D/HH:MM:SS

Para cada invocação do importador, o diretório de saída contém o seguinte:

Um arquivo ou arquivos com os mesmos nomes dos painéis originais do Grafana, mas agora no formato JSON do Cloud Monitoring.
Um arquivo report.json, que registra as seguintes informações para cada painel convertido:
- O nome e o local do arquivo do painel do Grafana que foi convertido.
- O nome e o local do arquivo convertido do painel do Monitoring.
- Avisos sobre recursos no painel do Grafana que não têm recurso correspondente no Cloud Monitoring e, portanto, não podem ser incluídos no painel convertido.
- Todos os erros que ocorreram na conversão.

Se você fez upload dos painéis, o diretório de relatórios também incluirá um arquivo upload_HH:MM:SS.txt, que inclui o URL para o qual o painel foi enviado.

Importar painéis do Grafana

Para converter os painéis do Grafana e fazer upload deles para o Cloud Monitoring, use o script import.sh:

./import.sh PATH_TO_DIRECTORY_OR_FILE PROJECT_ID

Esse script faz o seguinte:

Converte painéis em PATH_TO_DIRECTORY_OR_FILE do formato JSON usado pelo Grafana no formato JSON usado pelo Cloud Monitoring.
Faz upload dos painéis convertidos no seu projeto do Google Cloud PROJECT_ID usando a CLI do Google Cloud.

Se você não estiver autenticado na CLI gcloud, execute o comando gcloud auth login antes de executar o script import.sh.

É possível importar todos os painéis do Grafana em um diretório ou especificar um único painel nesse diretório.

Para importar todos os painéis do diretório GRAFANA_DASHBOARDS_DIR para o projeto PROJECT_ID do Google Cloud, especifique o diretório, em relação ao diretório do importador e o ID do projeto de destino ao invocar o script:
```
./import.sh GRAFANA_DASHBOARDS_DIR PROJECT_ID
```
Para converter apenas o painel MY_GRAFANA_DASHBOARD.json no diretório GRAFANA_DASHBOARDS_DIR, inclua o nome do arquivo do painel, relativo ao diretório importador, ao invocar o script:
```
./import.sh GRAFANA_DASHBOARDS_DIR/MY_GRAFANA_DASHBOARD.json PROJECT_ID
```

O importador de painel inclui um painel de amostra do Grafana como examples/k8s_cluster_example.json. O comando a seguir importa esse painel para o projeto especificado:

./import.sh examples/k8s_cluster_example.json PROJECT_ID

Quando invocada com o PROJECT_ID my-project-test-1, a saída é semelhante a esta:

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

Depois que o script import.sh cria o diretório de saída e converte os painéis, mas antes de fazer upload dos painéis convertidos para o projeto, ele solicita uma confirmação. Insira y e o script faz upload do painel e imprime o URL do novo painel:

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

Converter painéis do Grafana sem fazer upload

Se você quiser inspecionar ou editar os painéis convertidos antes de fazer o upload deles, omita o valor PROJECT_ID ao invocar o script import.sh:

./import.sh PATH_TO_DIRECTORY_OR_FILE

O importador converte os painéis conforme descrito em Importar painéis do Grafana, mas não faz upload dos painéis convertidos para o Cloud Monitoring.

É possível executar a etapa de upload mais tarde usando o script upload.sh manualmente.

Fazer upload de painéis manualmente

Para fazer o upload manual dos painéis no formato JSON do Cloud Monitoring, use o script upload.sh.

    ./upload.sh PATH_TO_DIRECTORY_OR_FILE PROJECT_ID

O script upload.sh usa a CLI do Google Cloud para fazer upload dos arquivos JSON. Se você não estiver autenticado na CLI gcloud, execute o comando gcloud auth login antes de executar o script upload.sh.

Para fazer upload de todos os painéis em um diretório reports/YYYY-M-D/HH:MM:SS, especifique o diretório, relativo ao diretório do importador e o ID do projeto de destino ao invocar o script:
```
./upload.sh reports/YYYY-M-D/HH:MM:SS PROJECT_ID
```
Ao fazer o upload de todos os painéis de um diretório, o script solicita que você continue ou saia antes de fazer o upload dos painéis.
Para fazer upload de um painel específico em um diretório reports/YYYY-M-D/HH:MM:SS, especifique o diretório e o nome do arquivo, em relação ao diretório do importador e o ID do projeto de destino ao invocar o script:
```
./upload.sh reports/YYYY-M-D/HH:MM:SS/MY_MONITORING_DASHBOARD.json PROJECT_ID
```
Ao fazer o upload de um único painel de um diretório, o script é executado sem solicitar que você faça o upload dos painéis.

Por exemplo, o comando a seguir faz upload de um painel armazenado em um subdiretório reports para o projeto my-project-test-1 do Google Cloud:

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

Solução de problemas

De vez em quando, publicamos pequenas atualizações e correções de bugs para a ferramenta. Antes de tentar solucionar outros problemas, primeiro tente corrigir o problema usando git pull para extrair a versão mais recente do repositório e importar novamente.

Para informações sobre problemas com os painéis convertidos, como gráficos que não mostram dados, consulte o arquivo README do importador.