PromQL es el lenguaje de consultas sobre el que se construye toda parte de Prometheus que lee datos: dashboards, reglas de alertas, depuración ad hoc. Esta guía construye una consulta real paso a paso: dado un counter de peticiones dividido por ruta, método y estado, encontrar cada ruta cuya tasa de errores supere el 5%.

Seleccionar series temporales

La expresión PromQL más simple es solo un nombre de métrica, que devuelve el valor actual de cada serie temporal con ese nombre:

http_requests_total

Añade selectores de etiquetas entre llaves para acotarlo a un subconjunto concreto:

http_requests_total{status="500"}

Esto devuelve cada serie llamada http_requests_total cuya etiqueta status sea exactamente "500", sin importar la ruta ni el método. Los selectores también pueden hacer coincidencia con expresiones regulares (status=~"5.." para cualquier estado 5xx) y negación (status!="200"), entre otros operadores.

De un counter a una tasa

http_requests_total es un counter: solo sube, así que su valor bruto (un número grande y siempre creciente desde que arrancó el proceso) no es lo que realmente quieres mirar. Lo que quieres es a qué velocidad aumenta, y eso es lo que calcula la función rate(): la tasa media de aumento por segundo durante una ventana de tiempo dada.

rate(http_requests_total{status="500"}[5m])

Esto devuelve, para cada serie que coincide, la tasa media por segundo de errores 500 durante los últimos 5 minutos. Una función relacionada, irate(), calcula una tasa instantánea usando solo los dos últimos puntos de datos del rango, en lugar de promediar toda la ventana. irate() reacciona más rápido a picos repentinos, pero también es más ruidosa y sensible a un único scrape inusual; rate() es la opción recomendada por defecto para dashboards y especialmente para alertas, donde normalmente lo que quieres es una señal más suave y menos propensa a picos. Recurre a irate() específicamente cuando mires un counter que cambia rápido en una escala de tiempo corta y quieras ver cambios instantáneos en lugar de una tendencia suavizada.

Agregar para quitar las etiquetas que no te importan

rate() sigue devolviendo un resultado por cada serie temporal original, una línea por cada combinación única de ruta, método y estado. Para obtener un solo número por ruta, sumado entre los métodos y estados que existan, usa un operador de agregación:

sum by (path) (rate(http_requests_total{status="500"}[5m]))

sum by (path) (...) suma las tasas, agrupando por la etiqueta path y descartando todas las demás etiquetas del resultado. Esta es la forma general de la agregación en PromQL: elige un operador (sum, avg, max, min, count y otros) y una cláusula by (...) que nombra qué etiquetas sobreviven en el resultado.

Combinar consultas con operadores binarios

Para calcular una tasa de errores como porcentaje, necesitas dos consultas agregadas, peticiones con error y peticiones totales, divididas entre sí:

sum by (path) (rate(http_requests_total{status="500"}[5m]))
/
sum by (path) (rate(http_requests_total[5m]))
* 100

PromQL empareja los dos lados de una operación binaria por sus etiquetas restantes, path en este caso, calculando la división para cada pareja que coincide en lugar de exigirte alinearlas manualmente. Multiplicar por 100 convierte la razón resultante en un porcentaje.

Filtrar el propio resultado

Envuelve toda la expresión para quedarte solo con los resultados que realmente superan un umbral:

(
  sum by (path) (rate(http_requests_total{status="500"}[5m]))
  /
  sum by (path) (rate(http_requests_total[5m]))
  * 100
) > 5

Esto devuelve solo las rutas cuyo porcentaje de errores calculado está ahora por encima de 5, que es exactamente la forma de consulta que envolverías en una regla de alertas para avisar a alguien cuando se cumple.

Convertir una consulta en una alerta

Una regla de alertas es una expresión PromQL más metadatos que describen qué hacer cuando se evalúa a algo:

groups:
  - name: example-alerts
    rules:
      - alert: HighErrorRatePerPath
        expr: |
          (
            sum by (path) (rate(http_requests_total{status="500"}[5m]))
            /
            sum by (path) (rate(http_requests_total[5m]))
            * 100
          ) > 5
        for: 10m
        labels:
          severity: page
        annotations:
          summary: "Error rate above 5% on {{ $labels.path }}"

for: 10m exige que la condición se mantenga durante 10 minutos antes de que la alerta se dispare realmente, lo que evita avisar por un breve pico que se resuelve solo. Prometheus evalúa reglas como esta continuamente y entrega todo lo que se esté disparando a Alertmanager, que es el mismo PromQL que de otro modo pondrías directamente en un panel de Grafana, solo que envuelto con un nombre, una duración y metadatos de enrutamiento.

Hacia dónde seguir

Esto cubre vectores instantáneos, cálculos de tasas, agregación y operadores binarios, suficiente para leer y escribir la gran mayoría de las consultas que encontrarás en dashboards y alertas existentes. PromQL tiene más allá de esto (funciones de vectores de rango más allá de rate, subconsultas, más operadores de agregación), bien documentado en la propia referencia de consultas de Prometheus, que vale la pena tener abierta mientras escribes tus primeras consultas reales.