PromQL para Cloud Monitoring

En este documento, se describe el uso de Prometheus Query Language (PromQL) en Cloud Monitoring. PromQL proporciona una alternativa a la interfaz basada en menús del Explorador de métricas para crear gráficos y paneles.

Puedes usar PromQL para consultar y graficar datos de Cloud Monitoring de las siguientes fuentes:

También puedes usar herramientas como Grafana para hacer gráficos con los datos de métricas transferidos a Cloud Monitoring. Las métricas disponibles incluyen las métricas 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.

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 recurso supervisado se asignan a una métrica si consultas la lista de métricas deGoogle Cloud . 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 de etiqueta 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 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 las 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 tu métrica de Prometheus usa caracteres especiales, excepto _ o :, o si las claves de tus etiquetas usan caracteres especiales, excepto _, debes crear tu 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 el ajuste de escala automático de forma 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 mala en Cloud Monitoring, y esta práctica genera un rendimiento de las consultas extremadamente bajo. 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. También puedes descubrir métricas con la IU de Cloud Monitoring.
  • La correlación de varias métricas es útil para ver cuántas muestras se recuperaron, transfirieron y cobraron por métrica. Cloud Monitoring te proporciona esta información en la página Administración de métricas. También puedes acceder a esta información como datos de métricas con la métrica de muestras procesadas o la métrica de muestras escritas por ID de atribución.

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.