Importa paneles de Grafana a Cloud Monitoring

Cloud Monitoring proporciona un importador que puedes usar para importar archivos de panel en el formato JSON de Grafana a Cloud Monitoring. En este documento, se describe cómo usar el importador para convertir paneles de Grafana y subirlos de forma opcional a tu proyecto de Google Cloud.

Puedes usar el importador para convertir paneles de Grafana y subirlos a Cloud Monitoring como una sola operación, o puedes realizar los pasos de conversión y carga por separado. Puedes elegir este enfoque si deseas editar los paneles convertidos antes de subirlos.

El importador convierte los archivos del panel en el formato JSON que usa Grafana en el formato JSON que usa Cloud Monitoring. Un panel convertido puede diferir del panel original de Grafana. Si un panel de Grafana usa funciones que no están disponibles en los paneles de Cloud Monitoring, esos aspectos del panel de Grafana no se convierten. Estas diferencias se enumeran en el resultado de la conversión. El importador solo está diseñado para controlar paneles que usan expresiones PromQL y fuentes de datos de Prometheus. Es posible que los paneles que usan otras formas de consulta o fuentes de datos no se importen de forma correcta.

Para obtener información sobre cómo importar alertas de Prometheus a Cloud Monitoring, consulta Migra reglas de alertas y receptores de Prometheus.

Antes de comenzar

Antes de poder instalar y ejecutar el importador del panel, debes hacer lo siguiente:

  1. Usa un entorno que admita secuencias de comandos de shell de Bash.
  2. Tener o instalar Git.
  3. Tener o instalar Node.js, versión 20.4.1 o posterior.
  4. Tener o instalar Google Cloud CLI. Si ya tienes instalada la CLI de gcloud, asegúrate de tener la versión más reciente mediante la ejecución del comando gcloud components update.

Obtén el importador del panel

El importador de paneles se almacena en el repositorio de GitHub monitoring-dashboard-samples. Para obtener el importador, haz lo siguiente:

  1. Clona el repositorio:

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

  2. Cambia al directorio del importador de panel:

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

El importador de paneles incluye las siguientes secuencias de comandos:

  • import.sh, que convierte los paneles y, de forma opcional, sube los paneles convertidos a Cloud Monitoring.

  • upload.sh, que sube los paneles convertidos, o cualquier panel de Monitoring, a Cloud Monitoring. La secuencia de comandos import.sh llama a esta secuencia de comandos para realizar la carga.

Cuando usas la secuencia de comandos import.sh, debes especificar la ubicación de los paneles de Grafana para convertir. El importador crea un directorio que contiene los paneles convertidos y otra información. En las siguientes secciones, se describen estos directorios.

Paneles de Grafana para convertir

Puedes usar el importador de paneles para convertir uno o más paneles a la vez si especificas una ruta de acceso a los archivos de paneles.

  • Puedes especificar la ruta de acceso a un directorio que contiene paneles. Solo se procesan los archivos en el directorio que tienen la extensión .json.

  • Puedes especificar la ruta de acceso a un solo archivo JSON. El nombre del archivo debe tener la extensión .json.

Paneles convertidos y otra información

Cuando el importador se ejecuta por primera vez, crea un subdirectorio reports. Cada vez que ejecutas el importador, obtienes un nuevo directorio de salida en el directorio reports, nombrado por la fecha y hora. El nombre del directorio de salida tiene la siguiente estructura:
reports/YYYY-M-D/HH:MM:SS

Para cada invocación del importador, el directorio de salida contiene lo siguiente:

  • Un archivo o archivos con los mismos nombres que los paneles originales de Grafana, pero ahora en formato JSON de Cloud Monitoring.
  • Un archivo report.json, que registra la siguiente información para cada panel convertido:
    • El nombre y la ubicación del archivo del panel de Grafana que se convirtió.
    • El nombre y la ubicación del archivo del panel de Monitoring convertido.
    • Nota sobre los atributos del panel de Grafana que no tienen un atributo correspondiente en Cloud Monitoring y, por lo tanto, no se pudieron incluir en el panel convertido.
    • Cualquier error que haya ocurrido en la conversión

Si subiste los paneles, el directorio de informes también incluye un archivo upload_HH:MM:SS.txt, que incluye la URL al que se subió el panel.

Importa paneles de Grafana

Para convertir los paneles de Grafana y subirlos a Cloud Monitoring, usa la secuencia de comandos import.sh:

./import.sh PATH_TO_DIRECTORY_OR_FILE PROJECT_ID

Esta secuencia de comandos hace lo siguiente:

  1. Convierte los paneles en PATH_TO_DIRECTORY_OR_FILE del formato JSON que usa Grafana al formato JSON que usa Cloud Monitoring.

  2. Sube los paneles convertidos en tu proyecto de Google Cloud PROJECT_ID con Google Cloud CLI

    Si no te validaste en la CLI de gcloud, ejecuta el comando gcloud auth login antes de ejecutar la secuencia de comandos import.sh.

Puedes importar todos los paneles de Grafana en un directorio o puedes especificar un solo panel en el directorio para importar.

  • Para importar todos los paneles del directorio GRAFANA_DASHBOARDS_DIR al proyecto PROJECT_ID de Google Cloud, especifica el directorio en relación con el directorio del importador y el ID del proyecto de destino cuando invoques la secuencia de comandos. :

    ./import.sh GRAFANA_DASHBOARDS_DIR PROJECT_ID

  • Para convertir solo el panel MY_GRAFANA_DASHBOARD.json en el directorio GRAFANA_DASHBOARDS_DIR, incluye el nombre del archivo del panel, en relación con el directorio del importador, cuando invoques la secuencia de comandos:

    ./import.sh GRAFANA_DASHBOARDS_DIR/MY_GRAFANA_DASHBOARD.json PROJECT_ID

El importador de paneles incluye un panel de Grafana de muestra como examples/k8s_cluster_example.json. Con el siguiente comando, se importa ese panel al proyecto especificado:

./import.sh examples/k8s_cluster_example.json PROJECT_ID

Cuando se invoca con my-project-test-1 PROJECT_ID, el resultado es similar al siguiente:

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

Después de que la secuencia de comandos import.sh cree el directorio de salida y convierta los paneles, pero antes de subir los paneles convertidos a tu proyecto, se te solicitará confirmación. Ingresa y, y la secuencia de comandos sube el panel y, luego, imprime la URL del panel nuevo:

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

Convierte paneles de Grafana sin subir

Si deseas inspeccionar o editar los paneles convertidos antes de subirlos, omite el valor PROJECT_ID cuando invoques la secuencia de comandos import.sh:

./import.sh PATH_TO_DIRECTORY_OR_FILE

El importador convierte los paneles como se describe en Importa los paneles de Grafana, pero no sube los paneles convertidos a Cloud Monitoring.

Puedes ejecutar el paso de carga más adelante con la secuencia de comandos upload.sh de forma manual.

Sube paneles de forma manual

Para subir paneles de forma manual en formato JSON de Cloud Monitoring, usa la secuencia de comandos upload.sh.

    ./upload.sh PATH_TO_DIRECTORY_OR_FILE PROJECT_ID

La secuencia de comandos upload.sh usa Google Cloud CLI para subir los archivos JSON. Si no te validaste en la CLI de gcloud, ejecuta el comando gcloud auth login antes de ejecutar la secuencia de comandos upload.sh.

  • Para subir todos los paneles en un directorio reports/YYYY-M-D/HH:MM:SS, especifica el directorio en relación con el directorio del importador y el ID del proyecto de destino cuando invoques la secuencia de comandos:

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

    Cuando subes todos los paneles desde un directorio, la secuencia de comandos te solicita que continúes o salgas antes de subir los paneles.

  • Para subir un panel específico en un directorio reports/YYYY-M-D/HH:MM:SS, especifica el directorio y el nombre de archivo, en relación con el directorio del importador y el ID del proyecto de destino cuando invocas la secuencia de comandos:

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

    Cuando subes un solo panel desde un directorio, la secuencia de comandos se ejecuta sin solicitarte antes de subir los paneles.

Por ejemplo, el siguiente comando sube un panel almacenado en un subdirectorio reports al proyecto de 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

Soluciona problemas

En ocasiones, publicamos pequeñas actualizaciones y correcciones de errores en la herramienta. Antes de intentar solucionar más problemas, primero intenta solucionar el problema a través de git pull para extraer la versión más reciente del repositorio y, luego, importarlo de nuevo.

Para obtener información sobre los problemas con los paneles convertidos, como los gráficos que no muestran datos, consulta el archivo README del importador.

¿Qué sigue?