Hacer consultas con Grafana

Una vez que hayas implementado Google Cloud Managed Service para Prometheus, podrás consultar los datos enviados al servicio gestionado y mostrar los resultados en gráficos y paneles.

En este documento se describen los ámbitos de las métricas, que determinan los datos que puedes consultar, y cómo usar Grafana para obtener y usar los datos que has recogido.

Todas las interfaces de consulta de Managed Service para Prometheus están configuradas para recuperar datos de Monarch mediante la API de Cloud Monitoring. Si consultas Monarch en lugar de consultar datos de servidores Prometheus locales, obtendrás una monitorización global a gran escala.

Antes de empezar

Si aún no has desplegado el servicio gestionado, configura la recogida gestionada o la recogida con despliegue automático. Puedes saltarte este paso si solo te interesa consultar métricas de Cloud Monitoring con PromQL.

Configurar el entorno

Para no tener que introducir repetidamente el ID del proyecto o el nombre del clúster, haz la siguiente configuración:

• Configura las herramientas de línea de comandos de la siguiente manera:

  • Configura gcloud CLI para que haga referencia al ID de tu proyectoGoogle Cloud :

    gcloud config set project PROJECT_ID
    

  • Configura la CLI de kubectl para que use tu clúster:

    kubectl config set-cluster CLUSTER_NAME
    

  Para obtener más información sobre estas herramientas, consulta los siguientes artículos:

  • Información general sobre la CLI de gcloud
  • Comandos de kubectl

Configurar un espacio de nombres

Crea el espacio de nombres de Kubernetes NAMESPACE_NAME para los recursos que crees como parte de la aplicación de ejemplo:

kubectl create ns NAMESPACE_NAME

Verificar las credenciales de la cuenta de servicio

Si tu clúster de Kubernetes tiene habilitada la federación de identidades de carga de trabajo para GKE, puedes saltarte esta sección.

Cuando se ejecuta en GKE, Managed Service para Prometheus obtiene automáticamente las credenciales del entorno en función de la cuenta de servicio predeterminada de Compute Engine. La cuenta de servicio predeterminada tiene los permisos necesarios, monitoring.metricWriter y monitoring.viewer, de forma predeterminada. Si no usas Workload Identity Federation para GKE y has quitado alguno de esos roles de la cuenta de servicio de nodo predeterminada, tendrás que volver a añadir los permisos que faltan antes de continuar.

Configurar una cuenta de servicio para Workload Identity Federation for GKE

Si tu clúster de Kubernetes no tiene habilitada la federación de identidades de carga de trabajo para GKE, puedes saltarte esta sección.

Managed Service para Prometheus captura datos de métricas mediante la API de Cloud Monitoring. Si tu clúster usa la federación de Workload Identity para GKE, debes conceder permiso a tu cuenta de servicio de Kubernetes para usar la API Monitoring. En esta sección se describe lo siguiente:

• Crear una Google Cloud cuenta de servicio gmp-test-sa.
• Asociar la cuenta de servicio Google Cloud a la cuenta de servicio de Kubernetes predeterminada en un espacio de nombres de prueba. NAMESPACE_NAME
• Conceder el permiso necesario a la cuenta de servicio Google Cloud .

Crear y vincular la cuenta de servicio

Este paso aparece en varios lugares de la documentación de Managed Service para Prometheus. Si ya has completado este paso en una tarea anterior, no tienes que repetirlo. Vaya a la sección Autorizar la cuenta de servicio.

La siguiente secuencia de comandos crea la cuenta de servicio gmp-test-sa y la vincula a la cuenta de servicio predeterminada de Kubernetes en el espacio de nombres NAMESPACE_NAME:

gcloud config set project PROJECT_ID \
&&
gcloud iam service-accounts create gmp-test-sa \
&&
gcloud iam service-accounts add-iam-policy-binding \
  --role roles/iam.workloadIdentityUser \
  --member "serviceAccount:PROJECT_ID.svc.id.goog[NAMESPACE_NAME/default]" \
  gmp-test-sa@PROJECT_ID.iam.gserviceaccount.com \
&&
kubectl annotate serviceaccount \
  --namespace NAMESPACE_NAME \
  default \
  iam.gke.io/gcp-service-account=gmp-test-sa@PROJECT_ID.iam.gserviceaccount.com

Si usas un espacio de nombres o una cuenta de servicio de GKE diferentes, ajusta los comandos según corresponda.

Autorizar la cuenta de servicio

Los grupos de permisos relacionados se recogen en roles, y tú asignas los roles a una entidad principal, en este ejemplo, la Google Cloudcuenta de servicio. Para obtener más información sobre los roles de Monitoring, consulta Control de acceso.

El siguiente comando otorga a la cuenta de servicio Google Cloud gmp-test-sa los roles de la API Monitoring que necesita para leer datos de métricas.

Si ya has concedido un rol específico a la Google Cloud cuenta de servicio como parte de una tarea anterior, no es necesario que lo hagas de nuevo.

gcloud projects add-iam-policy-binding PROJECT_ID \
  --member=serviceAccount:gmp-test-sa@PROJECT_ID.iam.gserviceaccount.com \
  --role=roles/monitoring.viewer \
&& \
gcloud projects add-iam-policy-binding PROJECT_ID \
  --member=serviceAccount:gmp-test-sa@PROJECT_ID.iam.gserviceaccount.com \
  --role=roles/iam.serviceAccountTokenCreator

Depurar la configuración de Workload Identity Federation para GKE

Si tienes problemas para que funcione Workload Identity Federation para GKE, consulta la documentación sobre cómo verificar la configuración de Workload Identity Federation para GKE y la guía para solucionar problemas de Workload Identity Federation para GKE.

Como las erratas y las acciones de copiar y pegar parciales son las fuentes de errores más habituales al configurar la federación de identidades de carga de trabajo para GKE, te recomendamos encarecidamente que uses las variables editables y los iconos de copiar y pegar en los que se puede hacer clic que se incluyen en los ejemplos de código de estas instrucciones.

Workload Identity Federation para GKE en entornos de producción

En el ejemplo que se describe en este documento, se vincula la Google Cloud cuenta de servicio Google Clouda la cuenta de servicio predeterminada de Kubernetes y se le otorgan todos los permisos necesarios para usar la API Monitoring.

En un entorno de producción, puede que quieras usar un enfoque más detallado, con una cuenta de servicio para cada componente, cada una con permisos mínimos. Para obtener más información sobre cómo configurar cuentas de servicio para la gestión de identidades de cargas de trabajo, consulta Usar Workload Identity Federation para GKE.

Permisos de consultas y métricas

Los datos que puedes consultar están determinados por la estructura de Cloud Monitoring ámbito de métricas, independientemente del método que utilices para consultar los datos. Por ejemplo, si usas Grafana para consultar datos de Managed Service para Prometheus, cada ámbito de métricas debe configurarse como una fuente de datos independiente.

Un permiso de métricas de Monitoring es una estructura de solo lectura que te permite consultar datos de métricas de varios proyectos de Google Cloud . Cada ámbito de las métricas está alojado en un Google Cloud proyecto designado, llamado proyecto de ámbito.

De forma predeterminada, un proyecto es el proyecto de ámbito de su propio ámbito de métricas, y el ámbito de métricas contiene las métricas y la configuración de ese proyecto. Un proyecto de ámbito puede tener más de un proyecto monitorizado en su ámbito de métricas, y el proyecto de ámbito puede ver las métricas y las configuraciones de todos los proyectos monitorizados que se incluyan en el ámbito de métricas. Un proyecto monitorizado también puede pertenecer a más de un ámbito de métricas.

Cuando consultas las métricas de un proyecto de ámbito y ese proyecto de ámbito aloja un ámbito de métricas de varios proyectos, puedes recuperar datos de varios proyectos. Si el ámbito de las métricas incluye todos tus proyectos, las consultas y las reglas se evalúan de forma global.

Para obtener más información sobre el ámbito de los proyectos y de las métricas, consulte Ámbitos de las métricas. Para obtener información sobre cómo configurar el ámbito de las métricas de varios proyectos, consulta Ver métricas de varios proyectos.

Datos de Managed Service para Prometheus en Cloud Monitoring

La forma más sencilla de verificar que tus datos de Prometheus se están exportando es usar la página Explorador de métricas de Cloud Monitoring en la Google Cloud consola, que admite PromQL. Para obtener instrucciones, consulta Consultar con PromQL en Cloud Monitoring.

También puedes importar tus paneles de Grafana a Cloud Monitoring. De esta forma, puedes seguir usando los paneles de Grafana personales o creados por la comunidad sin tener que configurar ni implementar una instancia de Grafana.

Grafana

Managed Service para Prometheus usa la fuente de datos de Prometheus integrada en Grafana, lo que significa que puedes seguir usando cualquier panel de control de Grafana personal o creado por la comunidad sin tener que hacer ningún cambio.

Implementar Grafana (si es necesario)

Si no tienes una implementación de Grafana en ejecución en tu clúster, puedes crear una implementación de prueba efímera para experimentar.

Para crear una implementación efímera de Grafana, aplica el archivo de manifiesto grafana.yaml de Managed Service para Prometheus a tu clúster y redirige los puertos del servicio grafana a tu máquina local. Debido a las restricciones de CORS, no puedes acceder a una implementación de Grafana mediante Cloud Shell.

1. Aplica el manifiesto grafana.yaml:

   kubectl -n NAMESPACE_NAME apply -f https://raw.githubusercontent.com/GoogleCloudPlatform/prometheus-engine/v0.15.3/examples/grafana.yaml
   

2. Redirecciona los puertos del servicio grafana a tu máquina local. En este ejemplo, se reenvía el servicio al puerto 3000:

   kubectl -n NAMESPACE_NAME port-forward svc/grafana 3000
   

   Este comando no devuelve nada y, mientras se ejecuta, informa de los accesos a la URL.

   Puedes acceder a Grafana en tu navegador a través de la URL http://localhost:3000 con el nombre de usuario y la contraseña admin:admin.

A continuación, añade una nueva fuente de datos de Prometheus a Grafana siguiendo estos pasos:

1. Ve a tu implementación de Grafana. Por ejemplo, puedes ir a la URL http://localhost:3000 para acceder a la página de bienvenida de Grafana.

2. Selecciona Conexiones en el menú principal de Grafana y, a continuación, Fuentes de datos.

   

3. Seleccione Añadir fuente de datos y, a continuación, Prometheus como base de datos de series temporales.

   

4. Asigna un nombre a la fuente de datos, define el campo URL como http://localhost:9090 y, a continuación, selecciona Guardar y probar. Puedes ignorar cualquier error que indique que la fuente de datos no está configurada correctamente.

5. Copia la URL del servicio local de tu implementación, que tendrá un aspecto similar al siguiente:

   http://grafana.NAMESPACE_NAME.svc:3000
   

Configurar y autenticar la fuente de datos de Grafana

Google Cloud Todas las APIs requieren autenticación mediante OAuth2. Sin embargo, Grafana no admite la autenticación OAuth2 para las cuentas de servicio que se usan con fuentes de datos de Prometheus. Para usar Grafana con Managed Service para Prometheus, utiliza el sincronizador de fuentes de datos para generar credenciales OAuth2 para tu cuenta de servicio y sincronizarlas con Grafana a través de la API de fuentes de datos de Grafana.

Debes usar el sincronizador de fuentes de datos para configurar y autorizar a Grafana a consultar datos de forma global. Si no sigues estos pasos, Grafana solo ejecutará consultas en los datos del servidor de Prometheus local.

El sincronizador de fuentes de datos es una herramienta de interfaz de línea de comandos que envía de forma remota valores de configuración a una fuente de datos de Grafana Prometheus determinada. De esta forma, te aseguras de que tu fuente de datos de Grafana tenga los siguientes elementos configurados correctamente:

• Autenticación, que se realiza actualizando periódicamente un token de acceso de OAuth 2.0
• El conjunto de APIs de Cloud Monitoring se ha definido como la URL del servidor de Prometheus.
• El método HTTP definido como GET
• El tipo y la versión de Prometheus se han definido en un mínimo de 2.40.x.
• Los valores de tiempo de espera de HTTP y de consulta se han establecido en 2 minutos.

El sincronizador de fuentes de datos debe ejecutarse repetidamente. Como los tokens de acceso de las cuentas de servicio tienen un tiempo de vida predeterminado de una hora, ejecutar el sincronizador de fuentes de datos cada 10 minutos te asegura que tienes una conexión autenticada ininterrumpida entre Grafana y la API Cloud Monitoring.

Puedes ejecutar el sincronizador de fuentes de datos mediante un CronJob de Kubernetes o con Cloud Run y Cloud Scheduler para disfrutar de una experiencia totalmente sin servidor. Si implementa Grafana de forma local, por ejemplo, con Grafana de código abierto o Grafana Enterprise, le recomendamos que ejecute el sincronizador de fuentes de datos en el mismo clúster en el que se ejecuta Grafana. Si usas Grafana Cloud, te recomendamos que elijas la opción totalmente sin servidor.

Ejecutar consultas con Grafana

Ahora puede crear paneles de control de Grafana y ejecutar consultas con la fuente de datos configurada. En la siguiente captura de pantalla se muestra un gráfico de Grafana que muestra la métrica up:

Para obtener información sobre cómo consultar Google Cloud métricas del sistema con PromQL, consulta PromQL para métricas de Cloud Monitoring.

Ejecutar el sincronizador de fuentes de datos fuera de GKE

Si ejecutas el sincronizador de fuentes de datos en un clúster de Google Kubernetes Engine o utilizas la opción sin servidor, puedes saltarte esta sección. Si tienes problemas de autenticación en GKE, consulta Verificar las credenciales de la cuenta de servicio.

Cuando se ejecuta en GKE, el sincronizador de fuentes de datos obtiene automáticamente las credenciales del entorno en función de la cuenta de servicio del nodo o de la configuración de Workload Identity Federation for GKE. En los clústeres de Kubernetes que no son de GKE, las credenciales deben proporcionarse explícitamente al sincronizador de fuentes de datos mediante la variable de entorno GOOGLE_APPLICATION_CREDENTIALS.

1. Define el contexto de tu proyecto de destino:

   gcloud config set project PROJECT_ID
   

2. Crea una cuenta de servicio:

   gcloud iam service-accounts create gmp-test-sa
   

   En este paso se crea la cuenta de servicio que puede que ya hayas creado en las instrucciones de Workload Identity Federation para GKE.

3. Concede los permisos necesarios a la cuenta de servicio:

   gcloud projects add-iam-policy-binding PROJECT_ID \
     --member=serviceAccount:gmp-test-sa@PROJECT_ID.iam.gserviceaccount.com \
     --role=roles/monitoring.viewer \
   && \
   gcloud projects add-iam-policy-binding PROJECT_ID \
     --member=serviceAccount:gmp-test-sa@PROJECT_ID.iam.gserviceaccount.com \
     --role=roles/iam.serviceAccountTokenCreator
   

4. Crea y descarga una clave para la cuenta de servicio:

   gcloud iam service-accounts keys create gmp-test-sa-key.json \
     --iam-account=gmp-test-sa@PROJECT_ID.iam.gserviceaccount.com
   

5. Define la ruta del archivo de claves mediante la variable de entorno GOOGLE_APPLICATION_CREDENTIALS.

Autorizar el sincronizador de fuentes de datos para obtener la monitorización de varios proyectos

Managed Service para Prometheus admite la monitorización de varios proyectos mediante ámbitos de métricas.

Si usas la opción sin servidor, podrás enviar consultas a varios proyectos si el proyecto que has elegido es el proyecto de acotación de un ámbito de métricas de varios proyectos.

Si vas a implementar el sincronizador de fuentes de datos en Kubernetes, tu proyecto local es tu proyecto de ámbito y has seguido las instrucciones para verificar o configurar una cuenta de servicio en el proyecto local, las consultas entre proyectos deberían funcionar sin necesidad de realizar más configuraciones.

Si tu proyecto local no es el proyecto de ámbito, debes autorizar la cuenta de servicio de computación predeterminada del proyecto local o tu cuenta de servicio de federación de identidades de carga de trabajo para GKE para que tenga acceso monitoring.viewer al proyecto de ámbito. A continuación, introduce el ID del proyecto de ámbito como valor de la variable de entorno PROJECT_ID.

Si usas la cuenta de servicio default de Compute Engine, puedes hacer una de las siguientes acciones:

• Implementa el sincronizador de fuentes de datos en un clúster que pertenezca a tu proyecto de ámbito.

• Habilita Workload Identity Federation for GKE en tu clúster y sigue los pasos de configuración.

• Proporciona una clave de cuenta de servicio explícita.

Para conceder a una cuenta de servicio los permisos necesarios para acceder a otro proyecto, haz lo siguiente: Google Cloud

1. Concede a la cuenta de servicio permiso para leer el proyecto de destino que quieras consultar:

   gcloud projects add-iam-policy-binding SCOPING_PROJECT_ID \
     --member=serviceAccount:gmp-test-sa@PROJECT_ID.iam.gserviceaccount.com \
     --role=roles/monitoring.viewer
   

2. Al configurar el sincronizador de fuentes de datos, introduce el ID del proyecto de ámbito como valor de la variable de entorno PROJECT_ID.

Inspeccionar el CronJob de Kubernetes

Si vas a implementar el sincronizador de fuentes de datos en Kubernetes, puedes inspeccionar el CronJob y asegurarte de que todas las variables estén configuradas correctamente ejecutando el siguiente comando:

kubectl describe cronjob datasource-syncer

Para ver los registros del trabajo que configura Grafana inicialmente, ejecuta el siguiente comando inmediatamente después de aplicar el archivo datasource-syncer.yaml:

kubectl logs job.batch/datasource-syncer-init

Desmontaje

Para inhabilitar el CronJob del sincronizador de fuentes de datos en Kubernetes, ejecuta el siguiente comando:

kubectl delete -f https://raw.githubusercontent.com/GoogleCloudPlatform/prometheus-engine/v0.15.3/cmd/datasource-syncer/datasource-syncer.yaml

Si inhabilitas el sincronizador de fuentes de datos, el Grafana vinculado dejará de actualizarse con credenciales de autenticación recientes y, por lo tanto, las consultas de Managed Service para Prometheus dejarán de funcionar.

Compatibilidad con APIs

Los siguientes endpoints de la API HTTP de Prometheus son compatibles con Managed Service para Prometheus en la URL con el prefijo https://monitoring.googleapis.com/v1/projects/PROJECT_ID/location/global/prometheus/api/v1/.

Para consultar la documentación completa, consulta la documentación de referencia de la API Cloud Monitoring. Los endpoints HTTP de Prometheus no están disponibles en las bibliotecas de cliente específicas de cada lenguaje de Cloud Monitoring.

Para obtener información sobre la compatibilidad con PromQL, consulta Compatibilidad con PromQL.

• Se admiten los siguientes endpoints:

  • /api/v1/query
  • /api/v1/query_range
  • /api/v1/metadata
  • /api/v1/labels
  • /api/v1/query_exemplars

• El endpoint /api/v1/label/<label_name>/values solo funciona si se proporciona la etiqueta __name__ usándola como valor de <label_name> o si se corresponde exactamente con ella mediante un selector de serie. Por ejemplo, se admiten las siguientes llamadas:

  • /api/v1/label/__name__/values
  • /api/v1/label/__name__/values?match[]={__name__=~".*metricname.*"}
  • /api/v1/label/labelname/values?match[]={__name__="metricname"}

  Esta limitación provoca que las consultas de variables label_values($label) en Grafana fallen. En su lugar, puedes usar label_values($metric, $label). Se recomienda este tipo de consulta porque evita obtener valores de etiquetas de métricas que no son relevantes para el panel de control en cuestión.

• El endpoint /api/v1/series se admite en las solicitudes GET, pero no en las POST. Si usas el sincronizador de fuentes de datos o el proxy frontend, esta restricción se gestiona automáticamente. También puede configurar sus fuentes de datos de Prometheus en Grafana para que solo emitan solicitudes GET. El parámetro match[] no admite coincidencias de expresiones regulares en la etiqueta __name__.

Siguientes pasos

• Usa alertas de PromQL en Cloud Monitoring.
• Configura la evaluación de reglas gestionadas.
• Configura los exportadores que se usan con frecuencia.