Nomenclatura de métricas y cardinalidad de etiquetas: unidades en el nombre, valores acotados en las etiquetas

Qué es

El nombre de una métrica dice qué se mide; las etiquetas dicen para qué corte. La guía de nomenclatura de Prometheus da las convenciones: un prefijo de aplicación o subsistema de una sola palabra (http_, process_), una unidad y una cantidad por métrica, unidades base (segundos, bytes, no milisegundos ni megabytes), la unidad como sufijo en plural, _total para recuentos acumulativos e _info para pseudométricas de metadatos. Ejemplos de la guía: http_request_duration_seconds, process_cpu_seconds_total, http_requests_total. La guía también establece una prueba: el sum() o avg() sobre todas las dimensiones de etiqueta de una métrica debería ser significativo; si no lo es, los datos pertenecen a dos métricas. Señala que otras convenciones, entre ellas OpenTelemetry, mantienen la unidad fuera del nombre y en los metadatos; Prometheus recomienda mantenerla en el nombre para que la configuración de alertas y paneles siga siendo legible sin un esquema.

Las etiquetas son las dimensiones: operation="create", stage="extract", un código de estado, una plantilla de ruta. La advertencia de la guía es la mitad importante: cada combinación única de valores de etiqueta es una nueva serie temporal, de modo que las etiquetas no deben llevar conjuntos no acotados como IDs de usuario o direcciones de correo electrónico.

Por qué importa

Una serie cuesta memoria, CPU, disco y red mientras exista. La guía de instrumentación da órdenes de magnitud: mantener la cardinalidad de una métrica por debajo de 10 como pauta, tratar cualquier valor por encima de 100 o con potencial de crecer como un caso para reducir dimensiones o para sacar el análisis del sistema de monitoreo, y esperar que la inmensa mayoría de las métricas no tengan etiquetas en absoluto. Un histograma clásico ingerido de la forma clásica multiplica el problema: cada bucket configurado crea una serie con el sufijo _bucket para cada combinación de etiquetas, esté poblada o no.

Cómo aplicarlo

• Nombrar por prefijo, cantidad, unidad, _total: queue_consumed_messages_total, job_last_success_timestamp_seconds.
• Usar plantillas de ruta, no rutas en bruto; clases o códigos de estado, no mensajes; solo valores tipo enum.
• Antes de añadir una etiqueta, estimar sus valores distintos y multiplicar por las combinaciones de etiquetas existentes y por los buckets del histograma.
• Trasladar el análisis por usuario o por solicitud a los registros o las trazas, donde una cardinalidad alta es normal.
• Fijar un límite de muestras por objetivo donde el servidor ofrezca uno (Prometheus: sample_limit en la configuración de scrape) y alertar sobre el crecimiento del número de series, para detectar una etiqueta problemática antes de que lo haga el servidor.

Trampas

Meter el significado de una etiqueta en el nombre de la métrica (http_requests_get_total) rompe la agregación. Mezclar segundos y milisegundos bajo un mismo nombre hace que las series colisionen en silencio. Los nombres de pod o de contenedor en las métricas de aplicación están acotados, pero cambian en cada despliegue, creando un nuevo conjunto de series cada vez. Los histogramas nativos cambian el modelo de coste de los buckets; la guía de histogramas citada explica las variantes.

Qué hace un límite de muestras al activarse

sample_limit es una última línea de defensa, no un filtro: cuando un objetivo lo supera, Prometheus trata todo el scrape como fallido, de modo que todas las métricas de ese servicio desaparecen a la vez y las alertas que las leen se quedan en silencio. Usarlo en tres pasos. Eliminar o agregar las etiquetas conocidas como riesgosas en metric_relabel_configs, de modo que una etiqueta problemática cueste una métrica y no el objetivo entero. Alertar cuando scrape_samples_post_metric_relabeling se acerque al límite por objetivo, y sobre prometheus_tsdb_head_series del servidor, para ver el crecimiento antes del corte. Luego fijar sample_limit bastante por encima del recuento normal, de modo que solo lo active algo desbocado. label_limit y los límites de longitud de etiqueta hacen fallar el scrape de la misma manera y merecen el mismo margen.