Es posible que parte de la información de esta página (o toda) no se aplique a Trusted Cloud de S3NS. Consulta Diferencias con Google Cloud para obtener más detalles.

Se usó la API de Cloud Translation para traducir esta página.

PromQL para Cloud Monitoring

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

Envía valores de configuración a una fuente de datos de Grafana.
Mantiene las credenciales de autenticación para una cuenta de servicio Trusted Cloud by S3NS 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 para usar PromQL en Cloud Monitoring. En este documento, se supone que ya conoces Grafana.

Autoriza 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 con un sincronizador de fuentes de datos para generar y sincronizar credenciales.

Usa el sincronizador de fuente de datos para la autorización

Trusted Cloud by S3NS Todas las APIs requieren autenticación a través de OAuth2. Sin embargo, Grafana no admite la autenticación de OAuth2 para cuentas de servicio que se usan con fuentes de datos de Prometheus. Para usar Grafana con Cloud Monitoring, debes usar 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 la fuente de datos de Grafana.

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

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 Prometheus de Grafana determinada. Esto garantiza que la fuente de datos de Grafana tenga configurado lo siguiente de forma correcta:

Autenticación, realizada con una actualización periódica de un token de acceso OAuth2
La API de Cloud Monitoring configurada como la URL del servidor de Prometheus
El método HTTP configurado como GET
El tipo y la versión de Prometheus configurados en un mínimo de 2.40.x
Los valores de tiempo de espera de HTTP y de consulta establecidos en 2 minutos

El sincronizador de fuente de datos debe ejecutarse de forma repetida. Como los tokens de acceso a la API deTrusted Cloud by S3NS tienen un ciclo de vida de una hora, ejecutar el sincronizador de fuentes de datos cada 10 minutos garantiza que tengas una conexión autenticada sin interrupciones entre Grafana y la API de Cloud Monitoring.

Configura y autentica la fuente de datos de Grafana

Puedes usar Grafana para consultar los datos de métricas de Cloud Monitoring desde los servicios de Google Kubernetes Engine o desde otros entornos. Las instrucciones usan variables editables para crear comandos ejecutables. Recomendamos usar las variables editables y los íconos de copiar y pegar en los que se puede hacer clic incorporados en las muestras de código.

GKE

Para implementar 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 para implementar el sincronizador de fuentes de datos.
Luego, asegúrate de configurar y autorizar de forma adecuada el sincronizador de fuentes de datos:
- Si usas Workload Identity Federation for 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 deseas ejecutar el sincronizador de fuente de datos.
- Si no usas Workload Identity Federation for 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 el clúster está configurado para proteger todo el tráfico en el clúster mediante TLS, debes usar https:// en la URL y autenticarte con una de las opciones de autenticación de TLS admitidas.
Elige la fuente de datos de Grafana de Prometheus que deseas usar para Cloud Monitoring, que puede ser una fuente de datos nueva o preexistente, y, luego, busca y escribe el UID de la fuente de datos. El UID de la fuente de datos se puede encontrar en la última parte de la URL cuando se explora o configuras una fuente de datos, por ejemplo. https://yourcompanyname.grafana.net/connections/datasources/edit/GRAFANA_DATASOURCE_UID. No copies toda la URL de la fuente de datos. Copia solo el identificador único en la URL.
Configura una cuenta de servicio de Grafana. Para ello, crea la cuenta de servicio y genera un token que esta usará:
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 Agregar cuenta de servicio, asígnale un nombre y otórgale la función “Administrador” en Grafana. Si tu versión de Grafana permite permisos más detallados, puedes usar el rol Fuentes de datos > Escritor.
3. Haz clic en Agregar token de cuenta de servicio.
4. Configura el vencimiento del token configurado como “Sin vencimiento” y haz clic en Generar token; luego, copia el token generado en el portapapeles para usarlo como GRAFANA_SERVICE_ACCOUNT_TOKEN en el siguiente paso.

Configura 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 durante la inicialización y, luego, cada 10 minutos: Si usas Workload Identity Federation for GKE, el valor de NAMESPACE_NAME debe ser el mismo espacio de nombres que vinculaste antes 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 recién configurada y verifica que el valor de la URL del servidor de Prometheus comience con https://monitoring.s3nsapis.fr. Es posible que debas 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 autocompletado de etiquetas funcione en Grafana.

Verifica las credenciales de la cuenta de servicio

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

Cuando se ejecuta en GKE, Cloud Monitoring recupera 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 for GKE y ya quitaste cualquiera de esos roles de la cuenta de servicio de nodo predeterminada, tendrás que volver a agregar esos permisos faltantes antes de continuar.

Configura una cuenta de servicio para Workload Identity Federation for GKE

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

Cloud Monitoring captura datos de métricas con la API de Cloud Monitoring. Si tu clúster usa Workload Identity Federation for GKE, debes otorgar permiso a tu cuenta de servicio de Kubernetes a la API de Monitoring. En esta sección, se describe lo siguiente:

Crea una Trusted Cloud by S3NS cuenta de servicio dedicada, SERVICE_ACCT_NAME.
Vincula la cuenta de servicio Trusted Cloud a la cuenta de servicio de Kubernetes predeterminada en un espacio de nombres de prueba,NAMESPACE_NAME.
Otorgar el permiso necesario a la cuenta de servicio de Trusted Cloud

Crea y vincula la cuenta de servicio

Este paso aparece en varios lugares en la documentación de Cloud Monitoring. Si ya realizaste este paso como parte de una tarea anterior, no es necesario que lo repitas. Ve a la sección Autoriza la cuenta de servicio.

Con la siguiente secuencia de comandos, se crea la cuenta de servicio SERVICE_ACCT_NAME y se la vincula a la cuenta de servicio de Kubernetes predeterminada 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-system.iam.gserviceaccount.com \
&&
kubectl annotate serviceaccount \
  --namespace NAMESPACE_NAME \
  default \
  iam.gke.io/gcp-service-account=SERVICE_ACCT_NAME@PROJECT_ID.s3ns-system.iam.gserviceaccount.com

Si usas un espacio de nombres o una cuenta de servicio de GKE diferentes, ajusta los comandos de forma adecuada.

Autoriza la cuenta de servicio

Los grupos de permisos relacionados se recopilan en roles y se otorgan los roles a una principal, en este ejemplo, la cuenta de servicio de Trusted Cloud. Para obtener más información sobre las funciones de Monitoring, consulta Control de acceso.

Con el siguiente comando, se otorga a la cuenta de servicio Trusted Cloud , SERVICE_ACCT_NAME, las funciones de la API de Monitoring que necesita para leer datos de métricas.

Si ya otorgaste a la cuenta de servicio Trusted Cloud un rol específico como parte de la tarea anterior, no necesitas volver a hacerlo.

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

Depura la configuración de Workload Identity Federation for GKE

Si tienes problemas para lograr que Workload Identity Federation for GKE funcione, consulta la documentación para verificar la configuración de Workload Identity Federation for GKE y la Guía de solución de problemas de la federación de Workload Identity Federation for GKE.

Como los errores tipográficos y de copia parcial son las fuentes de errores más comunes en la configuración de Workload Identity Federation for GKE, recomendamos usar las variables editables y los íconos de copiar y pegar en los que se puede hacer clic incorporados en las muestras de código de estas instrucciones.

Workload Identity Federation for GKE en entornos de producción

En el ejemplo descrito en este documento, se vincula la cuenta de servicio Trusted Cloud a la cuenta de servicio de Kubernetes predeterminada y se le otorga a la cuenta de servicio Trusted Cloudtodos los permisos necesarios para usar la API de Monitoring.

En un entorno de producción, se recomienda usar un enfoque más detallado, con una cuenta de servicio para cada componente, cada una con permisos mínimos. Si deseas obtener más información sobre la configuración de cuentas de servicio para la administración de Workload Identity, consulta Usa Workload Identity Federation for GKE.

En otro lugar

Para implementar y ejecutar el sincronizador de la fuente de datos en entornos que no sean de Google Kubernetes Engine, haz lo siguiente:

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

Configura 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
```

Otorga 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-system.iam.gserviceaccount.com \
 --role=roles/monitoring.viewer \
 && \
 gcloud projects add-iam-policy-binding PROJECT_ID \
 --member=serviceAccount:DS_SYNCER_SVCACCT_NAME@PROJECT_ID.s3ns-system.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-system.iam.gserviceaccount.com
```
La ruta de acceso a este directorio se usa para establecer una variable de entorno en un paso posterior. Para obtener la ruta de acceso, 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 para un clúster de Kubernetes configurado para proteger todo el tráfico en el clúster con TLS, debes usar https:// en la URL y, en el siguiente paso, autenticarte con una de las opciones de autenticación de TLS admitidas.
En Grafana, agrega una fuente de datos de Prometheus para usar con Cloud Monitoring y registra el UID de la fuente de datos:
1. Haz clic en Conexiones > Fuentes de datos > Agregar una fuente de datos nueva. Selecciona Prometheus en la lista de bases de datos de series temporales.
2. En el campo URL del servidor de Prometheus, ingresa el siguiente valor:
```
https://monitoring.s3nsapis.fr/v1/projects/PROJECT_ID/location/global/prometheus/
```
3. Haz clic en Guardar y probar.
  
  La URL en el navegador de la página de la fuente de datos contiene la IU de la fuente de datos, por ejemplo, https://yourcompanyname.grafana.net/connections/datasources/edit/GRAFANA_DATASOURCE_UID..
4. Registra el UID de la fuente de datos. Este valor se usa en el comando para ejecutar el sincronizador de fuentes de datos. No copies toda la URL de la fuente de datos. Copia solo el identificador único en la URL, que es un valor como ee0z3woqjah34e:
```
GRAFANA_DATASOURCE_UID
```
Configura una cuenta de servicio de Grafana. Para ello, crea la cuenta de servicio y genera un token que esta usará:
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 Agregar cuenta de servicio, asígnale un nombre y otórgale la función “Administrador” en Grafana.
3. Haz clic en Agregar token de cuenta de servicio.
4. Configura el vencimiento del token configurado como “Sin vencimiento” y haz clic en Generar token; luego, 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 la fuente de datos. Puedes ejecutar el sincronizador desde una imagen de contenedor precompilada con Docker, o bien puedes compilar el código desde la fuente y ejecutarlo de forma manual. El sincronizador de fuentes de datos es una aplicación de Go, por lo que debes tener instalado Go para compilar el sincronizador desde la fuente.
Docker

Ejecuta el sincronizador de fuentes de datos desde Docker con la imagen de contenedor gke.gcr.io/prometheus-engine/datasource-syncer:v0.15.3-gke.0. Para realizar pruebas, puedes ejecutar el sincronizador de forma manual. Después de verificar 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 y garantizar que la conexión no se interrumpa, ya que los tokens de acceso tienen una vida útil de una hora.

Usa el siguiente comando de Docker para ejecutar el sincronizador de la fuente 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 de cron que ejecute el sincronizador de la fuente de datos, haz lo siguiente:
1. Edita la tabla cron:
  cron -e
2. Agrega 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 cuando se ejecuta el sincronizador de fuentes de datos, consulta el documento README.
Código fuente
1. Para compilar el sincronizador de la fuente de datos por tu cuenta, 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 de acceso a este directorio se usa para establecer una variable de entorno en un paso posterior. Para obtener la ruta de acceso, 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 la fuente de datos. Para realizar pruebas, puedes ejecutar el sincronizador de forma manual. Después de verificar 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 y garantizar que la conexión no se interrumpa, ya que los tokens de acceso tienen una duración de una hora.
  
  Usa el siguiente comando para ejecutar el sincronizador de la fuente de datos de forma manual:
  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 de cron que ejecute el sincronizador de la fuente de datos, haz lo siguiente:
  1. Edita la tabla cron:
    
    cron -e
  2. Agrega 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 cuando se ejecuta el sincronizador de fuentes de datos, consulta el documento README.
Ve a la fuente de datos de Grafana recién configurada y verifica que el valor de la URL del servidor de Prometheus comience con https://monitoring.s3nsapis.fr. Es posible que debas 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 funcione en Grafana.

Cómo ver métricas en Grafana

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

Haz clic en Explorar en el panel de navegación o en la página Fuentes de datos.
En el campo Métrica, usa el menú desplegable para seleccionar una métrica. También puedes seleccionar Explorador de métricas para buscar métricas específicas. Si la métrica está asociada con más de un recurso supervisado, debes agregar un filtro de etiquetas monitored_resource a tu consulta y seleccionar un tipo de recurso.
Agrega más filtros de etiquetas y operaciones para construir tu consulta.

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

Consulta las métricas de Cloud Monitoring con PromQL

Las métricas de Cloud Monitoring se pueden consultar con la especificación UTF-8 para PromQL. Los nombres de métricas en UTF-8 deben estar entre comillas y moverse dentro de los corchetes. Los nombres de las etiquetas también deben estar entre comillas si contienen caracteres incompatibles con versiones anteriores. Para 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 valor de distribución de Cloud Monitoring se pueden consultar como histogramas de Prometheus, con el sufijo _count, _sum o _bucket agregado al nombre de la métrica.

Los gráficos y los paneles creados antes de la compatibilidad con UTF-8 consultan las métricas de Cloud Monitoring convirtiendo sus nombres en equivalentes heredados compatibles con PromQL. Para obtener más información sobre las reglas de conversión de PromQL heredado, consulta Asigna métricas de Cloud Monitoring a PromQL heredado.

Aprende acerca de PromQL

Para aprender los conceptos básicos del uso de PromQL, te recomendamos consultar la documentación de código abierto. Los siguientes recursos pueden ayudarte a comenzar:

Especifica un tipo de recurso supervisado

Cuando una métrica de Cloud Monitoring se asocia a un solo tipo de recurso supervisado de Cloud Monitoring, las consultas de PromQL funcionarán sin especificar un tipo de recurso de forma manual. Sin embargo, algunas métricas dentro de Cloud Monitoring, incluidas algunas métricas del sistema, se asignan a más de un tipo de recurso.

Puedes ver qué tipos de recursos supervisados se asignan a una métrica si consultas la lista de métricas deTrusted Cloud by S3NS . Cada entrada en la documentación enumera los tipos de recursos supervisados asociados en la primera columna de cada entrada debajo del tipo. Si no se enumeran tipos de recursos supervisados, la métrica se puede asociar con cualquier tipo.

Si una métrica está asociada con más de un tipo de recurso, debes especificar el tipo de recurso en tu consulta de PromQL. Existe una etiqueta especial, monitored_resource, que puedes usar para seleccionar el tipo de recurso.

Los tipos de recursos supervisados en la mayoría de los casos son una string corta, como gce_instance, pero a veces aparecen como URI completos, como monitoring.googleapis.com/MetricIngestionAttribution. Las consultas de PromQL bien formadas podrían 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 usas la etiqueta monitored_resource cuando es necesario, verás 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

Resuelve 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, puedes consultar la etiqueta de métrica de forma específica si agregas el prefijo metric_ al nombre de la clave de la etiqueta en tu consulta.

Por ejemplo, supongamos que tienes una etiqueta de recurso y una etiqueta de métrica llamadas pod_name en la métrica example.googleapis.com/user/widget_count.

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

Asigna nombres de métricas de Cloud Monitoring a PromQL heredado

Los nombres de las métricas de Cloud Monitoring incluyen dos componentes, un dominio (como compute.googleapis.com/) y una ruta de acceso (como instance/disk/max_read_ops_count). Debido a que PromQL heredado solo admite los caracteres especiales : y _, debes aplicar las siguientes reglas para que los nombres de métricas de Monitoring sean compatibles con PromQL heredado:

Reemplaza el primer / por :.
Reemplaza 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 heredado:

Nombre de la métrica de Cloud Monitoring	Nombre de la métrica de PromQL heredada
`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 valor de distribución de Cloud Monitoring se pueden consultar como histogramas de Prometheus, con el sufijo _count, _sum o _bucket agregado al nombre de la métrica:

Nombre de la métrica de Cloud Monitoring	Nombres de métricas de PromQL heredadas
`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 podría funcionar de manera un poco diferente que PromQL ascendente.

Las consultas de PromQL en Cloud Monitoring se evalúan de forma parcial en el backend de Monarch con un lenguaje de consultas interno, y existen algunas diferencias conocidas en los resultados de la consulta. Aparte de las diferencias que se mencionan en esta sección, PromQL en Cloud Monitoring está a la par de PromQL disponible en la versión 2.44 de Prometheus.

Es posible que las funciones de PromQL agregadas después de la versión 2.44 de Prometheus no sean compatibles.

Compatibilidad con UTF-8

PromQL para Cloud Monitoring admite consultas en UTF-8.

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

Sin embargo, si el nombre de la métrica de Prometheus usa caracteres especiales, excepto _ o :, o si las claves de etiquetas usan caracteres especiales, excepto _, debes crear la consulta según la especificación UTF-8 para PromQL.

Los nombres de métricas en UTF-8 deben estar entre comillas y dentro de los corchetes. Los nombres de etiquetas también deben estar entre comillas si contienen caracteres incompatibles con versiones anteriores. Los siguientes ejemplos de consultas válidas son todos 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"}

Coincidencias en nombres de métricas

Solo se admite la coincidencia exacta en los nombres de métricas. Debes incluir una coincidencia exacta del nombre de la métrica en tu consulta.

Recomendamos las siguientes soluciones alternativas para situaciones comunes que usan un comparador de expresiones regulares en la etiqueta __name__:

Las configuraciones del adaptador de Prometheus suelen usar el operador =~ para hacer coincidir varios nombres de métricas. Para corregir este uso, expande la configuración para usar una política separada para cada métrica y nombra cada métrica de forma explícita. Esto también evita que se realice un ajuste de escala automático accidental en métricas inesperadas.
Las expresiones regulares se suelen usar para representar varias métricas no dimensionales en el mismo gráfico. Por ejemplo, si tienes una métrica como cpu_servicename_usage, puedes usar un comodín para generar un gráfico de todos tus servicios juntos. Usar métricas no dimensionales como esta es una práctica explícitamente incorrecta en Cloud Monitoring, y esta práctica genera un rendimiento extremadamente bajo de las consultas. Para corregir este uso, traslada toda la dimensionalidad a las etiquetas de métricas en lugar de incorporar dimensiones en el nombre de la métrica.
Las consultas sobre varias métricas se suelen usar para ver qué métricas están disponibles para la consulta. En su lugar, te recomendamos que uses la llamada /labels/__name__/values para descubrir métricas.

Inactivo

La inactividad no es compatible con el backend de Monarch.

Cálculo de `irate`

Cuando el período de visualización de la función irate es menor que el tamaño del paso, aumentamos la ventana al tamaño del paso. Monarch requiere este cambio para garantizar que ninguno de los datos de entrada se ignore por completo en el resultado. Esta diferencia también se aplica a los cálculos de rate.

Cálculo de `rate` y `increase`

Cuando el período de visualización de la función rate es menor que el tamaño del paso, aumentamos la ventana al tamaño del paso. Monarch requiere este cambio para garantizar que ninguno de los datos de entrada se ignore por completo en el resultado. Esta diferencia también se aplica a los cálculos de irate.

Existen 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 generar resultados un poco diferentes. Por ejemplo, los ejemplos de contador Monarch se almacenan con un intervalo de tiempo en lugar de la marca de tiempo única que usa Prometheus. Por lo tanto, las muestras de contadores en Monarc se pueden incluir en un cálculo de frecuencia aunque la marca de tiempo de Prometheus las excluya. Por lo general, esto da como resultado resultados más precisos, en especial cuando se consulta el principio o el final de las series temporales subyacentes.

Cálculo de `histogram_quantile`

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

Las diferencias de cálculo de frecuencia también pueden afectar la entrada a las consultas histogram_quantile.

Funciones de tipo específico en métricas de tipado diferente

Aunque Prometheus upstream es de tipado débil, Monarch es de tipado fuerte. Esto significa que la ejecución de funciones específicas de un solo tipo en una métrica de tipado diferente (por ejemplo, ejecutar rate() en una métrica GAUGE o histogram_quantile() en una métrica COUNTER o sin tipado) no funciona en Cloud Monitoring, aunque estas funciones funcionan en Prometheus upstream.