PromQL para Cloud Monitoring

En este documento se describe cómo usar Prometheus Query Language (PromQL) en Cloud Monitoring. PromQL ofrece una alternativa a la interfaz basada en menús del explorador de métricas para crear gráficos y paneles de control.

Puedes usar PromQL para consultar y representar gráficamente datos de Cloud Monitoring de las siguientes fuentes:

También puedes usar herramientas como Grafana para representar gráficamente los datos de métricas insertados en Cloud Monitoring. Entre las métricas disponibles se incluyen las de Managed Service para Prometheus y las métricas de Cloud Monitoring documentadas en las listas de métricas. Para obtener información sobre cómo configurar Grafana y otras herramientas basadas en la API de Prometheus, consulta la documentación de Managed Service para Prometheus sobre Grafana.

También puedes importar tus paneles de Grafana a Cloud Monitoring.

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 dentro de las llaves. Los nombres de las etiquetas también deben ir 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 Google Cloud 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, usa
    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 muestran 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 los sufijos _count, _sum o _bucket añadidos 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, el PromQL de Cloud Monitoring está a la par del PromQL disponible en la versión 2.44 de Prometheus.

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 tener este aspecto: 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 las etiquetas usan caracteres especiales, excepto _, debe crear la 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 situaciones habituales en las 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 escale automáticamente 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 tienes una métrica como cpu_servicename_usage, puedes usar un comodín para representar gráficamente todos tus 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. También puedes descubrir métricas mediante la interfaz de Cloud Monitoring.
  • Asociar varias métricas es útil para ver cuántas muestras se han recogido, ingerido y cobrado por métrica. Cloud Monitoring te proporciona esta información en la página Gestión de métricas. También puede acceder a esta información como datos de métricas mediante la métrica Samples Ingested o la métrica Samples Written by Attribution ID.

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 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 en 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 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) no funciona en Cloud Monitoring, aunque estas funciones sí funcionen en Prometheus.