Cada parte de Prometheus, scraping, almacenamiento, PromQL, alertas, opera sobre la misma estructura subyacente: una serie temporal, identificada por un nombre y un conjunto de etiquetas, formada por un flujo de valores con marca de tiempo. Esta guía cubre esa estructura y el formato de texto plano que usan los targets para exponerla.

Una serie temporal es un nombre, un conjunto de etiquetas y un flujo de muestras

Un nombre de métrica describe qué se está midiendo: http_requests_total, process_open_fds, node_memory_available_bytes. Por sí solo, un nombre de métrica aún no es una única serie temporal, es una familia que las etiquetas subdividen en series individuales. Las etiquetas son pares clave-valor adjuntos a una métrica: method="GET", status="500", path="/api/users". La combinación de un nombre de métrica más un conjunto concreto de valores de etiquetas identifica exactamente una serie temporal.

http_requests_total{method="GET", status="200", path="/api/users"}
http_requests_total{method="GET", status="500", path="/api/users"}
http_requests_total{method="POST", status="200", path="/api/orders"}

Estas son tres series temporales distintas que comparten un nombre de métrica. Prometheus también adjunta automáticamente sus propias etiquetas, que identifican de qué target y job procede una serie, además de las que la propia aplicación eligió exponer.

Una muestra es un punto de una serie: una marca de tiempo de 64 bits en milisegundos (normalmente el momento del scrape) junto con un valor de coma flotante de 64 bits. Una serie es el flujo continuo de estas muestras que se acumula, una por scrape, a lo largo del tiempo.

Los cuatro tipos de métrica

Las librerías cliente de Prometheus exponen cuatro tipos de métrica, cada uno con un significado distinto a la hora de consultarlo:

• Counter: un valor que solo sube (o se reinicia a cero al reiniciar), como un total acumulado de peticiones gestionadas. Casi nunca lees el valor bruto de un counter; calculas una tasa de cambio sobre él, que se cubre en la guía de PromQL.
• Gauge: un valor que puede subir o bajar, como el uso actual de memoria o el número de peticiones en curso. Se lee directamente, a diferencia de un counter.
• Histogram: muestrea observaciones (duraciones de peticiones, tamaños de respuesta) en buckets configurables y expone un recuento y una suma junto a ellos, lo que permite calcular cuantiles (como “latencia del percentil 95”) a posteriori a partir de los datos de buckets almacenados.
• Summary: similar a un histogram, pero calcula los cuantiles en el cliente en el momento de la observación en lugar de a partir de buckets. Es más barato de consultar, pero los cuantiles de un summary no pueden agregarse entre instancias como pueden los buckets de un histogram, razón por la cual los histogramas son la opción más común para cualquier cosa que vayas a agregar en una flota.

Un tipo de histograma nativo, que almacena datos de histograma a resolución completa de forma más eficiente que la forma antigua con buckets, lleva un tiempo en desarrollo activo; consulta la documentación actual de Prometheus para conocer su madurez presente antes de depender de él, ya que exactamente cuán oficialmente soportado está ha ido cambiando en las versiones recientes.

El formato de exposición

Para que Prometheus pueda recopilar de un target, ese target sirve sus valores actuales por HTTP como texto plano, con una estructura específica y deliberadamente simple:

# HELP http_requests_total Total number of HTTP requests handled.
# TYPE http_requests_total counter
http_requests_total{method="GET", status="200"} 8420
http_requests_total{method="GET", status="500"} 12

# HELP process_open_fds Number of open file descriptors.
# TYPE process_open_fds gauge
process_open_fds 27

Las líneas # HELP y # TYPE son comentarios que aportan documentación y el tipo de la métrica; cualquier otra línea que no sea un comentario es el valor actual de una serie, como un nombre de métrica, sus etiquetas entre llaves y el propio valor. Como solo es una instantánea, una línea por serie que muestra su valor ahora mismo, no hay historial en la respuesta de un scrape; el historial solo existe una vez que Prometheus ha recopilado repetidamente la misma serie a lo largo del tiempo y ha almacenado cada resultado.

La simplicidad del formato es deliberada: está pensado para ser trivial de generar incluso sin una librería cliente, que es lo que hace realista obtener métricas de Prometheus de casi cualquier cosa, no solo del software con soporte oficial de librería.

Velo por ti mismo

Como el scraping es solo un HTTP GET, puedes ver las métricas actuales de cualquier target directamente en un navegador o con curl, sin ningún servidor Prometheus:

curl http://localhost:9100/metrics   # una instancia de node_exporter, por ejemplo

Esa salida es exactamente lo que recibe el propio Prometheus en cada scrape, lo que la convierte en un primer paso de resolución de problemas realmente útil: si un target no aparece correctamente en Prometheus, comprobar directamente su salida /metrics en bruto te dice si el problema está en el target o en algo de la propia configuración de scrape de Prometheus.

De dónde vienen las etiquetas y por qué importan después

Las propias etiquetas de un target (qué endpoint, qué método, qué código de estado) vienen de cómo se instrumentó la aplicación o el exporter. Prometheus añade las suyas encima, que identifican el job y la instancia concreta de la que se recopiló una serie. Juntas, estas etiquetas son sobre lo que operan la agregación y el filtrado de PromQL, lo que te permite preguntar por “la tasa de errores en cada instancia” o “la tasa de peticiones solo de esta ruta” sobre los mismos datos subyacentes, que es exactamente lo que cubre la siguiente guía de esta serie.