Es posible que parte o toda la información de esta página no se aplique a Trusted Cloud by S3NS. Para obtener más información, consulta las diferencias con Google Cloud.

Esta página se ha traducido con Cloud Translation API.

PromQL para Cloud Monitoring

En este documento se describe cómo configurar Grafana para leer datos de métricas de Cloud Monitoring. Después, puedes usar PromQL para visualizar y representar los datos. Grafana y Cloud Monitoring se vinculan mediante un proceso denominado sincronizador de fuentes de datos, que permite la comunicación entre una fuente de datos de Grafana y Cloud Monitoring. El sincronizador de fuentes de datos hace lo siguiente:

Envía valores de configuración a una fuente de datos de Grafana.
Mantiene las credenciales de autenticación de una Trusted Cloud by S3NS cuenta de servicio que puede leer datos de métricas de Cloud Monitoring.

En este documento se describe cómo configurar el sincronizador de fuentes de datos y se proporciona información específica sobre el uso de PromQL en Cloud Monitoring. En este documento se da por hecho que ya conoces Grafana.

Autorizar a Grafana para leer datos de métricas

En esta sección se describe cómo configurar la autorización entre Cloud Monitoring y Grafana mediante un sincronizador de fuentes de datos para generar y sincronizar credenciales.

Usar el sincronizador de fuentes de datos para la autorización

Trusted Cloud by S3NS 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 Cloud Monitoring, 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.

Configurar y autenticar la fuente de datos de Grafana

Puedes usar Grafana para consultar datos de métricas de Cloud Monitoring de servicios de Google Kubernetes Engine u otros entornos. Las instrucciones usan variables editables para crear comandos ejecutables. Te recomendamos que uses las variables editables y los iconos de copiar y pegar que se pueden hacer clic y que están insertados en los ejemplos de código.

GKE

Para desplegar y ejecutar el sincronizador de fuentes de datos en un clúster de Kubernetes, haz lo siguiente:

Elige un proyecto, un clúster y un espacio de nombres en los que implementar el sincronizador de fuentes de datos.
A continuación, asegúrate de configurar y autorizar correctamente el sincronizador de fuentes de datos:
- Si utilizas Workload Identity Federation para GKE, sigue las instrucciones para crear y autorizar una cuenta de servicio. Asegúrate de vincularlo al espacio de nombres de Kubernetes en el que quieras ejecutar el sincronizador de fuentes de datos.
- Si no usas la federación de identidades de carga de trabajo para GKE, verifica que no hayas modificado la cuenta de servicio predeterminada de Compute Engine.
Determina la URL de tu instancia de Grafana. Por ejemplo, https://yourcompanyname.grafana.net para una implementación de Grafana Cloud o http://grafana.NAMESPACE_NAME.svc:3000 para una instancia local configurada con el archivo YAML de implementación de prueba.

Si implementas Grafana de forma local y tu clúster está configurado para proteger todo el tráfico del clúster mediante TLS, debes usar https:// en tu URL y autenticarte con una de las opciones de autenticación TLS admitidas.
Elige la fuente de datos de Grafana Prometheus que quieras usar para Cloud Monitoring, que puede ser una fuente de datos nueva o una que ya tengas, y, a continuación, busca y anota el UID de la fuente de datos. El UID de la fuente de datos se encuentra en la última parte de la URL al explorar o configurar una fuente de datos. Por ejemplo: https://yourcompanyname.grafana.net/connections/datasources/edit/GRAFANA_DATASOURCE_UID. No copie toda la URL de la fuente de datos. Copia solo el identificador único de la URL.
Configura una cuenta de servicio de Grafana creando la cuenta de servicio y generando un token para que la cuenta lo use:
1. En la barra lateral de navegación de Grafana, haz clic en Administración > Usuarios y acceso > Cuentas de servicio.
2. Para crear la cuenta de servicio, haz clic en Añadir cuenta de servicio, asígnale un nombre y concédele el rol "Administrador" en Grafana. Si tu versión de Grafana permite permisos más granulares, puedes usar el rol Fuentes de datos > Escritor.
3. Haz clic en Añadir token de cuenta de servicio.
4. Selecciona "Sin vencimiento" en la opción de vencimiento del token y haz clic en Generar token. A continuación, copia el token generado en el portapapeles para usarlo como GRAFANA_SERVICE_ACCOUNT_TOKEN en el siguiente paso.

Define las siguientes variables de entorno con los resultados de los pasos anteriores:

# These values are required.
PROJECT_ID=SCOPING_PROJECT_ID # The value from Step 1.
GRAFANA_API_ENDPOINT=GRAFANA_INSTANCE_URL # The value from step 2. This is a URL.
DATASOURCE_UIDS=GRAFANA_DATASOURCE_UID # The value from step 3. This is not a URL.
GRAFANA_API_TOKEN=GRAFANA_SERVICE_ACCOUNT_TOKEN # The value from step 4.
GCM_ENDPOINT_OVERRIDE=--gcm-endpoint-override="https://monitoring.s3nsapis.fr/v1/projects/PROJECT_ID/location/global/prometheus/"

Ejecuta el siguiente comando para crear un CronJob que actualice la fuente de datos al inicializarse y, después, cada 10 minutos. Si usas la federación de identidades de carga de trabajo para GKE, el valor de NAMESPACE_NAME debe ser el mismo espacio de nombres que vinculaste anteriormente a la cuenta de servicio.

curl https://raw.githubusercontent.com/GoogleCloudPlatform/prometheus-engine/v0.15.3/cmd/datasource-syncer/datasource-syncer.yaml \
| sed 's|$DATASOURCE_UIDS|'"$DATASOURCE_UIDS"'|; s|$GRAFANA_API_ENDPOINT|'"$GRAFANA_API_ENDPOINT"'|; s|$GRAFANA_API_TOKEN|'"$GRAFANA_API_TOKEN"'|; s|$PROJECT_ID|'"$PROJECT_ID"'|;' s|$GCM_ENDPOINT_OVERRIDE|'"$GCM_ENDPOINT_OVERRIDE"'|; \
| kubectl -n NAMESPACE_NAME apply -f -

Ve a la fuente de datos de Grafana que acabas de configurar y comprueba que el valor de URL del servidor de Prometheus empieza por https://monitoring.s3nsapis.fr. Es posible que tengas que actualizar la página. Una vez verificada, ve a la parte inferior de la página y selecciona Guardar y probar. Debes seleccionar este botón al menos una vez para asegurarte de que la función de autocompletar etiquetas funcione en Grafana.

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, Cloud Monitoring 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.

Cloud Monitoring recoge 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 Trusted Cloud by S3NS cuenta de servicio SERVICE_ACCT_NAME.
Asociar la cuenta de servicio Trusted 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 Trusted Cloud .

Crear y vincular la cuenta de servicio

Este paso aparece en varios lugares de la documentación de Cloud Monitoring. 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 SERVICE_ACCT_NAME 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 SERVICE_ACCT_NAME \
&&
gcloud iam service-accounts add-iam-policy-binding \
  --role roles/iam.workloadIdentityUser \
  --member "serviceAccount:PROJECT_ID.svc.id.goog[NAMESPACE_NAME/default]" \
  SERVICE_ACCT_NAME@PROJECT_ID.s3ns.iam.gserviceaccount.com \
&&
kubectl annotate serviceaccount \
  --namespace NAMESPACE_NAME \
  default \
  iam.gke.io/gcp-service-account=SERVICE_ACCT_NAME@PROJECT_ID.s3ns.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 Trusted 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 Trusted Cloud SERVICE_ACCT_NAME los roles de la API Monitoring que necesita para leer datos de métricas.

Si ya has concedido un rol específico a la Trusted 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:SERVICE_ACCT_NAME@PROJECT_ID.s3ns.iam.gserviceaccount.com \
  --role=roles/monitoring.viewer \
&& \
gcloud projects add-iam-policy-binding PROJECT_ID \
  --member=serviceAccount:SERVICE_ACCT_NAME@PROJECT_ID.s3ns.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 Trusted Cloud cuenta de servicio Trusted 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.

De otro lugar

Para desplegar y ejecutar el sincronizador de fuentes de datos en entornos distintos de Google Kubernetes Engine, haga lo siguiente:

Configura una cuenta de servicio para que la use el sincronizador de fuentes de datos:

Define el proyecto predeterminado para los comandos de gcloud:
```
gcloud config set project PROJECT_ID
```
Crea una cuenta de servicio para que la use el sincronizador de fuentes de datos:
```
gcloud iam service-accounts create DS_SYNCER_SVCACCT_NAME
```

Da permiso a la cuenta de servicio para leer datos de métricas:

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

Crea una clave para la cuenta de servicio:
```
gcloud iam service-accounts keys create DS_SYNCER_SVCACCT_KEYFILE_NAME.json \
--iam-account DS_SYNCER_SVCACCT_NAME@PROJECT_ID.s3ns.iam.gserviceaccount.com
```
La ruta a este directorio se usa para definir una variable de entorno en un paso posterior. Para obtener la ruta, ejecuta el comando pwd y registra el valor:
```
pwd
DS_SYNCER_SVCACCT_KEYFILE_DIR
```

Determina la URL de tu instancia de Grafana. Por ejemplo, https://yourcompanyname.grafana.net para una implementación de Grafana Cloud o https://localhost:3000 para una instancia de prueba local. Este valor se usa en el comando para ejecutar el sincronizador de fuentes de datos.

Si implementas Grafana de forma local en un clúster de Kubernetes configurado para proteger todo el tráfico del clúster mediante TLS, debes usar https:// en tu URL y, en el siguiente paso, autenticarte con una de las opciones de autenticación TLS admitidas.
En Grafana, añade una fuente de datos de Prometheus para usarla en Cloud Monitoring y registra el UID de la fuente de datos:
1. Haz clic en Conexiones > Fuentes de datos > Añadir una fuente de datos. Seleccione Prometheus en la lista de bases de datos de series temporales.
2. En el campo URL del servidor de Prometheus, introduce el siguiente valor:
```
https://monitoring.s3nsapis.fr/v1/projects/PROJECT_ID/location/global/prometheus/
```
3. Haz clic en Guardar y probar.
  
  La URL de la página de la fuente de datos en el navegador contiene la interfaz de usuario de la fuente de datos. Por ejemplo, https://yourcompanyname.grafana.net/connections/datasources/edit/GRAFANA_DATASOURCE_UID.
4. Anota el UID de la fuente de datos. Este valor se usa en el comando para ejecutar el sincronizador de fuentes de datos. No copie toda la URL de la fuente de datos. Copia solo el identificador único de la URL, que es un valor como el siguiente: ee0z3woqjah34e:
```
GRAFANA_DATASOURCE_UID
```
Configura una cuenta de servicio de Grafana creando la cuenta de servicio y generando un token para que la cuenta de servicio lo use:
1. En la barra lateral de navegación de Grafana, haz clic en Administración > Usuarios y acceso > Cuentas de servicio.
2. Para crear la cuenta de servicio, haz clic en Añadir cuenta de servicio, asígnale un nombre y concédele el rol "Administrador" en Grafana.
3. Haz clic en Añadir token de cuenta de servicio.
4. Selecciona "Sin vencimiento" en la opción de vencimiento del token y haz clic en Generar token. A continuación, copia el token generado en la siguiente variable editable. Este valor se usa en el comando para ejecutar el sincronizador de fuentes de datos.
```
GRAFANA_SERVICE_ACCOUNT_TOKEN
```
Ejecuta el sincronizador de fuentes de datos. Puedes ejecutar el sincronizador desde una imagen de contenedor prediseñada mediante Docker o compilar el código desde la fuente y ejecutarlo manualmente. El sincronizador de fuentes de datos es una aplicación de Go, por lo que debes tener Go instalado para compilar el sincronizador a partir del código fuente.
Docker

Ejecuta el sincronizador de fuentes de datos desde Docker mediante la imagen de contenedor gke.gcr.io/prometheus-engine/datasource-syncer:v0.15.3-gke.0. Para hacer pruebas, puedes ejecutar el sincronizador manualmente. Una vez que hayas verificado que la conexión funciona, como los tokens de acceso tienen una validez de una hora, debes usar un mecanismo automatizado, como un trabajo cron, para ejecutar el sincronizador de fuentes de datos cada 10 minutos y asegurarte de que la conexión no se interrumpa.

Usa el siguiente comando de Docker para ejecutar el sincronizador de fuentes de datos:
```
docker run --network container:grafana -v "DS_SYNCER_SVCACCT_KEYFILE_DIR/DS_SYNCER_SVCACCT_KEYFILE_NAME.json:/app/DS_SYNCER_SVCACCT_KEYFILE_NAME.json" gke.gcr.io/prometheus-engine/datasource-syncer:v0.15.3-gke.0
-datasource-uids=UID_OF_GRAFANA_DATASOURCE
-grafana-api-token=GRAFANA_SERVICE_ACCOUNT_TOKEN
-grafana-api-endpoint=URL_OF_GRAFANA_INSTANCE
-project-id=PROJECT_ID
-query.credentials-file=DS_SYNCER_SVCACCT_KEYFILE_DIR/DS_SYNCER_SVCACCT_KEYFILE_NAME.json
-gcm-endpoint-override="https://monitoring.s3nsapis.fr/v1/projects/PROJECT_ID/location/global/prometheus/"
```
Para crear un trabajo cron que ejecute el sincronizador de fuentes de datos, haz lo siguiente:
1. Edita la tabla cron:
  cron -e
2. Añade una entrada que ejecute el comando anterior cada 10 minutos:
  */10 * * * * * docker run --network container:grafana -v "DS_SYNCER_SVCACCT_KEYFILE_DIR/DS_SYNCER_SVCACCT_KEYFILE_NAME.json:/app/<KEY_ID>" gke.gcr.io/prometheus-engine/datasource-syncer:v0.15.3-gke.0 -datasource-uids=UID_OF_GRAFANA_DATASOURCE -grafana-api-token=GRAFANA_SERVICE_ACCOUNT_TOKEN -grafana-api-endpoint=URL_OF_GRAFANA_INSTANCE -project-id=PROJECT_ID -query.credentials-file=DS_SYNCER_SVCACCT_KEYFILE_DIR/DS_SYNCER_SVCACCT_KEYFILE_NAME.json -gcm-endpoint-override="https://monitoring.s3nsapis.fr/v1/projects/PROJECT_ID/location/global/prometheus/"
Para obtener más información sobre las opciones de línea de comandos disponibles al ejecutar el sincronizador de fuentes de datos, consulta el documento README.
Código fuente
1. Para crear el sincronizador de fuentes de datos, haz lo siguiente:
  1. Crea un directorio para contener el código y cambia a ese directorio:
    
    mkdir data-source-syncer-code cd data-source-syncer-code
    
    La ruta a este directorio se usa para definir una variable de entorno en un paso posterior. Para obtener la ruta, ejecuta el comando pwd y regístrala en la variable editable:
    
    pwd PATH_TO_LOCAL_REPO_COPY
  2. Clona el código de la versión actual del repositorio:
    
    git clone -b 'v0.15.3' --single-branch https://github.com/GoogleCloudPlatform/prometheus-engine
  3. Ve al directorio datasource-syncer y compila el código:
    
    cd prometheus-engine/cmd/datasource-syncer go build main.go
2. Ejecuta el sincronizador de fuentes de datos. Para hacer pruebas, puedes ejecutar el sincronizador manualmente. Una vez que hayas verificado que la conexión funciona, debes usar un mecanismo automatizado, como un trabajo cron, para ejecutar el sincronizador de fuentes de datos cada 10 minutos, ya que los tokens de acceso tienen una duración de una hora. De esta forma, te asegurarás de que la conexión no se interrumpa.
  
  Usa el siguiente comando para ejecutar el sincronizador de fuentes de datos manualmente:
  main -datasource-uids=UID_OF_GRAFANA_DATASOURCE -grafana-api-token=GRAFANA_SERVICE_ACCOUNT_TOKEN -grafana-api-endpoint=URL_OF_GRAFANA_INSTANCE -project-id=PROJECT_ID -query.credentials-file=DS_SYNCER_SVCACCT_KEYFILE_DIR/DS_SYNCER_SVCACCT_KEYFILE_NAME.json -gcm-endpoint-override="https://monitoring.s3nsapis.fr/v1/projects/PROJECT_ID/location/global/prometheus/"
  Para crear un trabajo cron que ejecute el sincronizador de fuentes de datos, haz lo siguiente:
  1. Edita la tabla cron:
    
    cron -e
  2. Añade una entrada que ejecute el comando anterior cada 10 minutos:
    
    */10 * * * * * main -datasource-uids=UID_OF_GRAFANA_DATASOURCE -grafana-api-token=GRAFANA_SERVICE_ACCOUNT_TOKEN -grafana-api-endpoint=URL_OF_GRAFANA_INSTANCE -project-id=PROJECT_ID -query.credentials-file=DS_SYNCER_SVCACCT_KEYFILE_DIR/DS_SYNCER_SVCACCT_KEYFILE_NAME.json -gcm-endpoint-override="https://monitoring.s3nsapis.fr/v1/projects/PROJECT_ID/location/global/prometheus/"
  Para obtener más información sobre las opciones de línea de comandos disponibles al ejecutar el sincronizador de fuentes de datos, consulta el documento README.
Ve a la fuente de datos de Grafana que acabas de configurar y comprueba que el valor de URL del servidor de Prometheus empieza por https://monitoring.s3nsapis.fr. Es posible que tengas que actualizar la página. Una vez verificada, ve a la parte inferior de la página y haz clic en Guardar y probar. Debes hacer clic en este botón al menos una vez para asegurarte de que la función de autocompletado de etiquetas de Grafana funciona.

Ver métricas en Grafana

Para ver las métricas de tu Trusted Cloud proyecto en Grafana, haz lo siguiente:

En el panel de navegación, haga clic en Explorar o en la página Fuentes de datos.
En el campo Métrica, utilice el menú desplegable para seleccionar una métrica. También puede seleccionar Explorador de métricas para buscar métricas concretas. Si la métrica está asociada a más de un recurso monitorizado, debes añadir un filtro de etiqueta monitored_resource a tu consulta y seleccionar un tipo de recurso.
Añade más filtros de etiquetas y operaciones para crear tu consulta.

Para obtener información sobre cómo crear visualizaciones y paneles de control en Grafana, consulta Paneles y visualizaciones.

Consultar métricas de Cloud Monitoring mediante PromQL

Las métricas de Cloud Monitoring se pueden consultar mediante la especificación UTF-8 de PromQL. Los nombres de métricas UTF-8 deben ir entre comillas y colocarse dentro de las llaves. Los nombres de las etiquetas también deben incluirse entre comillas si contienen caracteres no compatibles con versiones anteriores. En el caso de la métrica de Cloud Monitoring kubernetes.io/container/cpu/limit_utilization, las siguientes consultas son equivalentes:

{"kubernetes.io/container/cpu/limit_utilization", pod_name="foo"}
{__name__="kubernetes.io/container/cpu/limit_utilization", pod_name="foo"}.
{"__name__"="kubernetes.io/container/cpu/limit_utilization", "pod_name"="foo"}.

Las métricas con valores de distribución de Cloud Monitoring se pueden consultar como los histogramas de Prometheus, con los sufijos _count, _sum o _bucket añadidos al nombre de la métrica.

Los gráficos y los paneles de control creados antes de que se implementara la compatibilidad con UTF-8 consultan las métricas de Cloud Monitoring convirtiendo sus nombres en equivalentes antiguos compatibles con PromQL. Para obtener más información sobre las reglas de conversión de PromQL antiguas, consulta Asignar métricas de Cloud Monitoring a PromQL antiguo.

Aprender a usar PromQL

Para aprender los conceptos básicos de PromQL, te recomendamos que consultes la documentación de código abierto. Los siguientes recursos pueden ayudarte a empezar:

Especificar un tipo de recurso monitorizado

Cuando una métrica de Cloud Monitoring está asociada a un solo tipo de recurso monitorizado de Cloud Monitoring, las consultas de PromQL funcionarán sin necesidad de especificar manualmente un tipo de recurso. Sin embargo, algunas métricas de Cloud Monitoring, incluidas algunas métricas del sistema, se asignan a más de un tipo de recurso.

Para ver qué tipos de recursos supervisados se corresponden con una métrica, consulta la lista de Trusted Cloud by S3NS métricas. En cada entrada de la documentación se indican los tipos de recursos monitorizados asociados en la primera columna de cada entrada, debajo del tipo. Si no se indica ningún tipo de recurso monitorizado, la métrica se puede asociar a cualquier tipo.

Si una métrica está asociada a más de un tipo de recurso, debe especificar el tipo de recurso en su consulta de PromQL. Hay una etiqueta especial, monitored_resource, que puede usar para seleccionar el tipo de recurso.

Los tipos de recursos monitorizados suelen ser cadenas cortas, como gce_instance, pero en ocasiones aparecen como URIs completos, como monitoring.googleapis.com/MetricIngestionAttribution. Las consultas PromQL bien formadas pueden tener el siguiente aspecto:

logging_googleapis_com:byte_count{monitored_resource="k8s_container"}
loadbalancing_googleapis_com:l3_external_egress_bytes_count{monitored_resource="loadbalancing.googleapis.com/ExternalNetworkLoadBalancerRule"}

Si no usa la etiqueta monitored_resource cuando es necesario, recibirá el siguiente error:

metric is configured to be used with more than one monitored resource type; series selector must specify a label matcher on monitored resource name

Resolver conflictos de etiquetas

En Cloud Monitoring, las etiquetas pueden pertenecer a la métrica o al recurso. Si una etiqueta de métrica tiene el mismo nombre de clave que una etiqueta de recurso, puede hacer referencia a la etiqueta de métrica específicamente añadiendo el prefijo metric_ al nombre de la clave de la etiqueta en su consulta.

Por ejemplo, supongamos que tiene una etiqueta de recurso y una etiqueta de métrica con el nombre pod_name en la métrica example.googleapis.com/user/widget_count.

Para filtrar por el valor de la etiqueta de recurso, usa
example_googleapis_com:user_widget_count{pod_name="RESOURCE_LABEL_VALUE"}
Para filtrar por el valor de la etiqueta de la métrica, use
example_googleapis_com:user_widget_count{metric_pod_name="METRIC_LABEL_VALUE"}

Asignar nombres de métricas de Cloud Monitoring a PromQL antiguo

Los nombres de las métricas de Cloud Monitoring incluyen dos componentes: un dominio (como compute.googleapis.com/) y una ruta (como instance/disk/max_read_ops_count). Como la versión antigua de PromQL solo admite los caracteres especiales : y _, debe aplicar las siguientes reglas para que los nombres de las métricas de Monitoring sean compatibles con la versión antigua de PromQL:

Sustituye el primer / por :.
Sustituye todos los demás caracteres especiales (incluidos . y otros caracteres / ) por _.

En la siguiente tabla se enumeran algunos nombres de métricas y sus equivalentes de PromQL antiguos:

Nombre de la métrica de Cloud Monitoring	Nombre de métrica de PromQL antiguo
`compute.googleapis.com/instance/cpu/utilization`	`compute_googleapis_com:instance_cpu_utilization`
`logging.googleapis.com/log_entry_count`	`logging_googleapis_com:log_entry_count`

Las métricas con valores de distribución de Cloud Monitoring se pueden consultar como histogramas de Prometheus, con el sufijo _count, _sum o _bucket añadido al nombre de la métrica:

Nombre de la métrica de Cloud Monitoring	Nombres de métricas de PromQL antiguos
`networking.googleapis.com/vm_flow/rtt`	`networking_googleapis_com:vm_flow_rtt_sum` `networking_googleapis_com:vm_flow_rtt_count` `networking_googleapis_com:vm_flow_rtt_bucket`

Compatibilidad con PromQL

PromQL para Cloud Monitoring puede funcionar de forma ligeramente diferente a PromQL upstream.

Las consultas de PromQL en Cloud Monitoring se evalúan parcialmente en el backend de Monarch mediante un lenguaje de consulta interno, y hay algunas diferencias conocidas en los resultados de las consultas. Aparte de las diferencias que se indican en esta sección, la versión de PromQL de Cloud Monitoring es igual a la de Prometheus 2.44.

Es posible que no se admitan las funciones de PromQL añadidas después de la versión 2.44 de Prometheus.

Compatibilidad con UTF-8

PromQL para Cloud Monitoring admite consultas UTF-8.

Si el nombre de tu métrica de Prometheus solo contiene caracteres alfanuméricos más los caracteres _ o :, y si las claves de tus etiquetas solo contienen caracteres alfanuméricos más el carácter _, puedes hacer consultas con la sintaxis tradicional de PromQL. Por ejemplo, una consulta válida podría ser la siguiente: job:my_metric:sum{label_key="label_value"}.

Sin embargo, si el nombre de tu métrica de Prometheus usa caracteres especiales, excepto _ o :, o si tus claves de etiqueta usan caracteres especiales, excepto _, debes crear tu consulta de acuerdo con la especificación UTF-8 de PromQL.

Los nombres de métricas UTF-8 deben incluirse entre comillas y colocarse entre llaves. Los nombres de las etiquetas también deben incluirse entre comillas si contienen caracteres no compatibles con versiones anteriores. Las siguientes consultas válidas de ejemplo son equivalentes:

{"my.domain.com/metric/name_bucket", "label.key"="label.value"}
{__name__="my.domain.com/metric/name_bucket", "label.key"="label.value"}
{"__name__"="my.domain.com/metric/name_bucket", "label.key"="label.value"}

Coincidencia por nombre de métrica

Solo se admite la coincidencia exacta de nombres de métricas. Debe incluir una coincidencia exacta del nombre de la métrica en su consulta.

Te recomendamos las siguientes soluciones alternativas para los casos habituales en los que se usa un buscador de expresiones regulares en la etiqueta __name__:

Las configuraciones del adaptador de Prometheus suelen usar el operador =~ para buscar coincidencias en varios nombres de métricas. Para corregir este uso, amplíe la configuración para usar una política independiente para cada métrica y asigne un nombre explícito a cada métrica. De esta forma, también se evita que se aplique el autoescalado por error en métricas inesperadas.
Las expresiones regulares se suelen usar para representar gráficamente varias métricas no dimensionales en el mismo gráfico. Por ejemplo, si tiene una métrica como cpu_servicename_usage, puede usar un comodín para representar gráficamente todos sus servicios juntos. Usar métricas no dimensionales como esta es una práctica inadecuada en Cloud Monitoring, y lleva a un rendimiento de las consultas extremadamente bajo. Para corregir este uso, mueva toda la dimensionalidad a las etiquetas de métricas en lugar de insertar dimensiones en el nombre de la métrica.
Las consultas de varias métricas se suelen usar para ver qué métricas se pueden consultar. En su lugar, te recomendamos que uses la llamada /labels/__name__/values para descubrir métricas.

Falta de actualización

La obsolescencia no se admite en el backend de Monarch.

Cálculo de `irate`

Si la ventana retrospectiva de la función irate es inferior al tamaño del paso, aumentamos la ventana hasta el tamaño del paso. Monarch requiere este cambio para asegurarse de que no se ignore por completo ningún dato de entrada en la salida. Esta diferencia también se aplica a los cálculos de rate.

Cálculo de `rate` y `increase`

Si la ventana retrospectiva de la función rate es inferior al tamaño del paso, aumentamos la ventana hasta el tamaño del paso. Monarch requiere este cambio para asegurarse de que no se ignore por completo ningún dato de entrada en la salida. Esta diferencia también se aplica a los cálculos de irate.

Hay diferencias en los cálculos de interpolación y extrapolación. Monarch usa un algoritmo de interpolación diferente al de Prometheus, y esta diferencia puede dar lugar a resultados ligeramente distintos. Por ejemplo, las muestras de contador de Monarch se almacenan con un intervalo de tiempo en lugar de con la única marca de tiempo que usa Prometheus. Por lo tanto, las muestras de contador de Monarch se pueden incluir en un cálculo de la tasa, aunque la marca de tiempo de Prometheus las excluya. Por lo general, esto da como resultado tasas más precisas, sobre todo cuando se consulta el principio o el final de la serie temporal subyacente.

Cálculo de `histogram_quantile`

Un cálculo de PromQL histogram_quantile en un histograma sin muestras produce un valor NaN. El cálculo del lenguaje de consulta interno no produce ningún valor, sino que se elimina el punto de la marca de tiempo.

Las diferencias en el cálculo de las tarifas también pueden afectar a las entradas de las consultas histogram_quantile.

Funciones específicas de tipo en métricas de tipos diferentes

Aunque Prometheus upstream tiene un tipado débil, Monarch tiene un tipado fuerte. Esto significa que no se pueden ejecutar funciones específicas de un solo tipo en una métrica de otro tipo (por ejemplo, ejecutar rate() en una métrica GAUGE o histogram_quantile() en una métrica COUNTER o sin tipo) en Cloud Monitoring, aunque estas funciones sí funcionen en Prometheus.