Consulta de métricas de Prometheus mediante la API y PromQL

Artículo
03/04/2024

El servicio administrado de Azure Monitor para Prometheus, recopila métricas de clústeres de Azure Kubernetes y las almacena en un área de trabajo de Azure Monitor. PromQL (lenguaje de consulta de Prometheus) es un lenguaje de consulta funcional que te permite consultar y agregar datos de series temporales. Use PromQL para consultar y agregar métricas almacenadas en un área de trabajo de Azure Monitor.

En este artículo se describe cómo consultar un área de trabajo de Azure Monitor mediante PromQL a través de la API de REST. Para más información sobre PromQL, consulte Consulta de Prometheus.

Prerrequisitos

Para consultar un área de trabajo de Azure Monitor mediante PromQL, necesita los siguientes requisitos previos:

Un clúster de Azure Kubernetes o un clúster remoto de Kubernetes.
Servicio administrado de Azure Monitor para Prometheus que extrae métricas de un clúster de Kubernetes.
Un área de trabajo de Azure Monitor donde se almacenan las métricas de Prometheus.

Autenticación

Para consultar el área de trabajo de Azure Monitor, autentíquese mediante Microsoft Entra ID. La API admite la autenticación de Microsoft Entra mediante credenciales de cliente. Registre una aplicación cliente en Microsoft Entra ID y solicite un token.

Para configurar la autenticación de Microsoft Entra, siga estos pasos:

Registro de una aplicación con Microsoft Entra ID
Conceda acceso a la aplicación al área de trabajo de Azure Monitor.
Solicite un token.

Registro de una aplicación con Microsoft Entra ID

Para registrar una aplicación, siga los pasos descritos en Registro de una aplicación para solicitar tokens de autorización y trabajar con las API.

Permitir el acceso de la aplicación al área de trabajo

Asigne el rol Lector de datos de supervisión a la aplicación para que pueda consultar datos desde el área de trabajo de Azure Monitor.

Abra el área de trabajo de Azure Monitor en Azure Portal.
En la página de información general, tome nota del punto de conexión de consulta para su uso en la solicitud de REST.
Seleccione Control de acceso (IAM).
Seleccione Agregar y, luego, Agregar asignación de roles en la página Control de acceso (IAM).
En la página Agregar asignación de roles, busque Supervisión.
Seleccione el lector de datos de supervisión y, a continuación, seleccione la pestaña Miembros.
Elija Seleccionar miembros.
Busque la aplicación que registró y selecciónela.
Elija Seleccionar.
Seleccione Revisar y asignar.

Has creado un registro de aplicación y le has dado acceso para consultar datos desde el área de trabajo de Azure Monitor. Ahora puede generar un token y usarlo en una consulta.

Solicitud de un token

Envíe la siguiente solicitud del símbolo del sistema o use un cliente como Postman.

curl -X POST 'https://login.microsoftonline.com/<tennant ID>/oauth2/token' \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=<your apps client ID>' \
--data-urlencode 'client_secret=<your apps client secret>' \
--data-urlencode 'resource=https://prometheus.monitor.azure.com'

Muestra de cuerpo de respuesta:

{
    "token_type": "Bearer",
    "expires_in": "86399",
    "ext_expires_in": "86399",
    "expires_on": "1672826207",
    "not_before": "1672739507",
    "resource": "https:/prometheus.monitor.azure.com",
    "access_token": "eyJ0eXAiOiJKV1Qi....gpHWoRzeDdVQd2OE3dNsLIvUIxQ"
}

Guarde el token de acceso de la respuesta para su uso en las siguientes solicitudes HTTP.

Punto de conexión de consulta

Busca el punto de conexión de consulta del área de trabajo de Azure Monitor en la página de información general del área de trabajo de Azure Monitor.

API admitidas

Se admiten las siguientes consultas:

Consultas instantáneas

Para más información, consulte Consultas instantáneas.

Ruta de acceso: /api/v1/query
Ejemplos:

POST https://k8s-02-workspace-abcd.eastus.prometheus.monitor.azure.com/api/v1/query  
--header 'Authorization:  Bearer <access token>'
--header 'Content-Type: application/x-www-form-urlencoded' 
--data-urlencode 'query=sum( \
    container_memory_working_set_bytes \
    * on(namespace,pod) \
    group_left(workload, workload_type) \
    namespace_workload_pod:kube_pod_owner:relabel{ workload_type="deployment"}) by (pod)'

GET 'https://k8s02-workspace-abcd.eastus.prometheus.monitor.azure.com/api/v1/query?query=container_memory_working_set_bytes' 
--header 'Authorization:  Bearer <access token>'

Consultas por rango

Para más información, consulte Consultas por rango.
Ruta de acceso: /api/v1/query_range
Ejemplos:

GET 'https://k8s02-workspace-abcd.eastus.prometheus.monitor.azure.com/api/v1/query_range?query=container_memory_working_set_bytes&start=2023-03-01T00:00:00.000Z&end=2023-03-20T00:00:00.000Z&step=6h'
--header 'Authorization: Bearer <access token>

POST 'https://k8s02-workspace-abcd.eastus.prometheus.monitor.azure.com/api/v1/query_range' 
--header 'Authorization:  Bearer <access token>'
--header 'Content-Type: application/x-www-form-urlencoded' 
--data-urlencode 'query=up' 
--data-urlencode 'start=2023-03-01T20:10:30.781Z' 
--data-urlencode 'end=2023-03-20T20:10:30.781Z' 
--data-urlencode 'step=6h'

Serie

Para obtener más información, consulte Series.

Ruta de acceso: /api/v1/series
Ejemplos:

POST 'https://k8s02-workspace-abcd.eastus.prometheus.monitor.azure.com/api/v1/series' 
--header 'Authorization: Bearer <access token>
--header 'Content-Type: application/x-www-form-urlencoded' 
--data-urlencode 'match[]=kube_pod_info{pod="bestapp-123abc456d-4nmfm"}'

GET 'https://k8s02-workspace-abcd.eastus.prometheus.monitor.azure.com/api/v1/series?match[]=container_network_receive_bytes_total{namespace="default-1669648428598"}'

Etiquetas

Para obtener más información, consulte la ruta de acceso de Etiquetas: /api/v1/labels
Ejemplos:

GET 'https://k8s02-workspace-abcd.eastus.prometheus.monitor.azure.com/api/v1/labels'

POST 'https://k8s02-workspace-abcd.eastus.prometheus.monitor.azure.com/api/v1/labels'

Valores de etiqueta

Para obtener más información, vea Valores de etiqueta.
Ruta de acceso: /api/v1/label/__name__/values.

Nota

__name__ es la única versión admitida de esta API y devuelve todos los nombres de métricas. No se admiten otros valores /api/v1/label/<label_name>/values.

Ejemplo:

GET 'https://k8s02-workspace-abcd.eastus.prometheus.monitor.azure.com/api/v1/label/__name__/values'

Para obtener la especificación completa de las API de OSS prom, consulte API HTTP de Prometheus.

Limitaciones de API

Las siguientes limitaciones se agregan a las que se detallan en la especificación de Prometheus.

La consulta debe tener como ámbito una métrica
Cualquier consulta de captura de series temporales (/series o /query o /query_range) debe contener un buscador de coincidencias de etiqueta __name__. Es decir, cada consulta debe tener como ámbito una métrica. Solo puede haber un buscador de coincidencias de etiqueta __name__ en una consulta.
La consulta o serie no admite el filtro de expresiones regulares
Intervalo de tiempo admitido
- La API /query_range admite un intervalo de tiempo de 32 días. Este es el intervalo de tiempo máximo permitido, incluidos los selectores de intervalo especificados en la propia consulta. Por ejemplo, la consulta rate(http_requests_total[1h] de las últimas 24 horas significaría que los datos se consultan durante 25 horas. Esto procede del intervalo de 24 horas más la hora especificada en la propia consulta.
- La API /series captura datos para un intervalo de tiempo máximo de 12 horas. Si endTime no se proporciona, endTime = time.now(). Si el intervalo de tiempo es mayor que 12 horas, startTime se establece en endTime – 12h.
Intervalo de tiempo omitido
Se omiten la hora de inicio y la hora de finalización proporcionadas con /labels y /label/__name__/values, y se consultan todos los datos retenidos en el área de trabajo de Azure Monitor.
Características experimentales
No se admiten características experimentales, como patrones guiados.

Para más información sobre los límites de métricas de Prometheus, consulte Métricas de Prometheus.

Distinción entre mayúsculas y minúsculas

Prometheus administrado por Azure es un sistema que no distingue mayúsculas de minúsculas. Trata cadenas, como nombres de métricas, nombres de etiqueta o valores de etiqueta, como la misma serie temporal si difieren de otra serie temporal solo por el uso de mayúsculas y minúsculas de la cadena.

Nota:

Este comportamiento es diferente a Prometheus de código abierto nativo, que es un sistema que distingue mayúsculas de minúsculas.

En Prometheus administrado por Azure, las siguientes series temporales se consideran iguales:

diskSize(cluster="eastus", node="node1", filesystem="usr_mnt")
diskSize(cluster="eastus", node="node1", filesystem="usr_MNT")

Los ejemplos anteriores son una sola serie temporal en una base de datos de serie temporal.

Las muestras ingeridas en ellos se almacenan como si se extrajesen o ingiriesen en una sola serie temporal.
Si los ejemplos anteriores se ingieren con la misma marca de tiempo, se quita aleatoriamente uno de ellos.
Las mayúsculas y minúsculas que se almacenan en la base de datos de series temporales y que devuelven una consulta son impredecibles. Se pueden devolver mayúsculas y minúsculas diferentes en distintos momentos para la misma serie temporal.
Cualquier buscador de coincidencias de nombre o valor de la métrica presente en la consulta se recupera de la base de datos de serie temporal mediante la realización de una comparación sin distinción entre mayúsculas y minúsculas. Si hay un buscador de coincidencias que distingue mayúsculas de minúsculas en una consulta, se trata automáticamente como un buscador de coincidencias que no distingue mayúsculas de minúsculas al realizar comparaciones de cadenas.

Se recomienda asegurarse de que se produce o se extrae una serie temporal mediante el uso sistemático solo de mayúsculas o solo de minúsculas.

En Open Source Prometheus, las series temporales anteriores se tratan como dos series temporales diferentes. Todas las muestras que se extraen o ingieren se almacenan por separado.

Preguntas más frecuentes

Esta sección proporciona respuestas a preguntas comunes.

Me faltan todas o algunas métricas. ¿Cómo se puede solucionar el problema?

Puede usar la guía de solución de problemas para la ingesta de métricas de Prometheus desde el agente administrado aquí.

¿Por qué faltan métricas que tienen dos etiquetas con el mismo nombre excepto por las mayúsculas y minúsculas diferentes?

Veo algunas lagunas en los datos de métricas, ¿por qué ocurre esto?

Durante las actualizaciones de nodos, es posible que vea una brecha de 1 a 2 minutos en los datos de métricas para las métricas recopiladas de nuestros recopiladores de nivel de clúster. Esta brecha se debe a que el nodo en el que se ejecutan los datos se está actualizando como parte de un proceso de actualización normal. Este proceso de actualización afecta a los destinos de todo el clúster, como kube-state-metrics, y a los destinos de aplicación personalizados que se especifiquen. Esto ocurre cuando el clúster se actualiza de forma manual o mediante una actualización automática. Este comportamiento es esperado y se produce debido a la actualización del nodo en el que se ejecuta. Este comportamiento no afecta a ninguna de nuestras reglas de alerta recomendadas.

Pasos siguientes

Información general del área de trabajo de Azure Monitor
Administración de un área de trabajo de Azure Monitor
Introducción al servicio administrado para Prometheus de Azure Monitor
Consulta de métricas de Prometheus con libros de Azure