En 07-01 abrimos CicloUrbana por dentro con Actuator: sondas de salud, información de versión, niveles de log en caliente, un endpoint propio y una cadena de seguridad que exige ADMIN en el puerto 8081. Cerramos aquella lección dejando deliberadamente un endpoint sin abrir, /actuator/metrics, con una promesa: la instrumentación quedaba montada y aquí se leería.

Ha llegado el momento, y con una necesidad concreta detrás. En 09-01 ajustamos el rendimiento a base de pruebas de carga y EXPLAIN ANALYZE, es decir, mirando una vez y en un entorno controlado. En 09-02 montamos cachés cuya utilidad depende por completo de una tasa de aciertos que todavía nadie observa. Las dos lecciones dejaron la misma deuda: CicloUrbana no se mide sola, continuamente y en producción.

Esta lección la salda. No repetiremos qué es Actuator ni cómo se expone: usaremos la infraestructura ya montada para instrumentar de verdad. Veremos Micrometer como fachada de métricas, los cinco tipos de medidor y cuándo usar cada uno, el catálogo de métricas que existen sin escribir una línea, la regla de oro de la cardinalidad —la que separa un sistema de monitorización sano de uno que se cae por su propio peso—, las métricas de negocio de la red de Ribalta, la diferencia crucial entre percentiles calculados en el cliente e histogramas agregables, y el modelo unificado de observación de Spring Boot 3 que produce a la vez métrica y traza.

1. Los tres pilares de la observabilidad
2. Micrometer: el SLF4J de las métricas
3. Los tipos de medidor
4. Las métricas que ya existen sin escribir código
5. Consultar métricas desde /actuator/metrics
6. Etiquetas y la regla de oro de la cardinalidad
7. Instrumentar CicloUrbana: MetricasCicloUrbana
8. El Gauge, la referencia débil y su error clásico
9. @Timed y @Counted
10. Percentiles frente a histogramas
11. MeterFilter y MeterRegistryCustomizer
12. El pool, la base de datos y la caché: qué números vigilar
13. La Observation API: una instrumentación, dos señales
14. De las métricas a los SLO: RED y USE
15. Probar que una métrica se registra
16. Errores Comunes y Consejos
17. Ejercicios

Monitorizar es vigilar un conjunto conocido de indicadores; observar es poder responder preguntas que no habías previsto. La diferencia se nota a las tres de la mañana, cuando el problema nunca es el que esperabas. Para lograrlo hacen falta tres señales, y ninguna sustituye a las otras:

El flujo de trabajo real de una incidencia en Ribalta usa las tres en este orden: una alerta basada en métricas avisa de que el p99 de los alquileres se ha disparado; una traza muestra que el 80 % del tiempo está en el span de la pasarela de pagos; los logs de esa traza concreta, filtrados por su identificador, dicen qué error devolvió. Métricas para detectar, trazas para localizar, logs para entender.

Esta lección construye el primer pilar dentro de la aplicación. En 09-04 esas métricas saldrán del proceso hacia Prometheus y Grafana, porque —y conviene decirlo ya— todo lo que instrumentemos aquí vive en memoria y muere con el proceso.

La comparación es literal y explica el diseño entero. Igual que SLF4J te deja escribir log.info(...) sin saber si detrás hay Logback o Log4j2, Micrometer te deja registrar un contador sin saber si detrás hay Prometheus, Datadog, New Relic o CloudWatch. Tu código depende de una fachada; el sistema de destino es una dependencia intercambiable.

MeterRegistry es la pieza central: la fábrica y el registro de todos los medidores. Spring Boot crea uno automáticamente al detectar Actuator, y se inyecta como cualquier otro bean. Sin ninguna implementación concreta en el classpath se usa un SimpleMeterRegistry en memoria, que es justo lo que hace útil /actuator/metrics en desarrollo y en pruebas (apartado 15).

Un detalle importante de vocabulario: en Micrometer un medidor (meter) es la abstracción genérica, y Counter, Gauge, Timer, DistributionSummary y LongTaskTimer son sus tipos. Cada medidor se identifica por su nombre más su conjunto de etiquetas, y cada combinación distinta es una serie temporal independiente. Esa frase es la clave del apartado 6.

Cuatro criterios de elección que resuelven casi todas las dudas:

Counter frente a Gauge. Si la pregunta es «¿cuántas veces ha ocurrido?», es un contador; si es «¿cuánto hay ahora mismo?», es un indicador. Un contador nunca se decrementa: para «alquileres en curso» no se usa un contador que sube al iniciar y baja al finalizar —eso es un Gauge—, porque el valor de un contador es su ritmo de crecimiento, que es lo que rate() sabrá explotar en 09-04.

Timer frente a DistributionSummary. El Timer mide tiempo y lleva unidades; el DistributionSummary mide cualquier magnitud. La duración de un trayecto de bicicleta en minutos parece tiempo, pero no es la duración de una operación del programa: es un dato de negocio, y va en un DistributionSummary.

Timer frente a LongTaskTimer. Un Timer solo registra la operación cuando termina: si una importación tarda cuarenta minutos, durante esos cuarenta minutos el Timer no dice nada. El LongTaskTimer informa de las tareas activas y de cuánto llevan, que es justo lo que se quiere vigilar de una tarea @Scheduled de 07-03.

Todo Timer es también un contador. Publica _count, _sum y _max, así que temporizar una operación da gratis el número de veces que ocurrió: no hace falta un Counter aparte.

Antes de instrumentar nada, conviene saber qué hay. Con Actuator y las autoconfiguraciones activas, CicloUrbana ya publica:

Dos observaciones. La primera: http.server.requests sola responde a casi todo, porque tiene recuento (tráfico), etiqueta status (errores) y distribución (latencia), que son las tres señales del método RED. La segunda: spring.data.repository.invocations requiere activarse (management.metrics.data.repository.autotime.enabled: true) y es el complemento natural del contador de consultas de 09-01, ahora en producción y de forma continua.

Recordando la configuración de 07-01 —puerto de gestión 8081 y ADMIN por httpBasic—, basta con añadir el endpoint a la lista expuesta:

Esas tres etiquetas comunes son la diferencia entre «la latencia está alta» y «la latencia está alta en la instancia 3 de producción». Se aplican a todos los medidores, incluidos los automáticos.

Lo importante es cómo se lee: TOTAL_TIME / COUNT es la latencia media —4021,83 s entre 128.431 peticiones = 31 ms—, y ya sabemos de 09-01 lo poco que vale una media. Para acercarse a lo que importa se filtra con ?tag=, encadenando varios:

Fíjate en la etiqueta uri: dice /api/v1/alquileres/{id}/finalizar, con la plantilla y no con el identificador real. Esa decisión de Spring es la que hace utilizable la métrica, y es exactamente el tema del apartado siguiente.

Y una limitación que conviene interiorizar: este endpoint da el valor acumulado ahora. No hay historia, no hay gráfica, no hay «hace dos horas». Sirve para comprobar que una métrica existe y para una consulta puntual de urgencia; para todo lo demás hace falta 09-04.

Una etiqueta (tag, o label en Prometheus) es una dimensión: permite desglosar alquileres.iniciados por tipo de tarifa o http.server.requests por endpoint. Sin etiquetas, una métrica solo dice «pasan cosas»; con ellas, dice qué cosas.

Pero cada combinación distinta de nombre y valores de etiqueta es una serie temporal independiente, con su propia memoria en la aplicación, su propia serie en Prometheus y su propio coste en cada consulta. De ahí la regla de oro:

La cardinalidad de una etiqueta debe ser baja y acotada. Si el número de valores posibles crece con el número de usuarios, de peticiones o de filas, no es una etiqueta.

Aplicado a CicloUrbana:

Qué pasa exactamente cuando se incumple. Supón Counter.builder("alquileres.iniciados").tag("usuario", idUsuario). Con 50.000 ciudadanos aparecen 50.000 series: la aplicación retiene 50.000 objetos medidor en memoria y su MeterRegistry crece sin parar; /actuator/prometheus pasa de devolver 200 KB a devolver decenas de megabytes en cada recogida; Prometheus multiplica su consumo de memoria e índice; y las consultas de Grafana se vuelven lentas o directamente fallan. Es la causa número uno de caídas de sistemas de monitorización, tiene nombre propio —cardinality explosion— y lo peor es que no falla el día que se despliega, sino tres semanas después, cuando ya nadie relaciona una cosa con la otra.

La regla práctica que evita el error: si un dato identifica a un individuo o a una petición concreta, va en un log (09-05) o en una traza (09-06), nunca en una etiqueta de métrica. Las métricas responden «cuántos» y «cuánto»; el «cuál» es trabajo de las otras dos señales.

Un caso intermedio que conviene conocer: en Ribalta, 40 estaciones son una etiqueta perfectamente sana. Si CicloUrbana se extendiera a una red metropolitana de 4.000 estaciones habría que revisar la decisión —4.000 series por métrica multiplicadas por cada métrica de estación empieza a ser mucho— y probablemente pasar a etiquetar por distrito y dejar la estación concreta para las trazas.

Las métricas automáticas dicen si el sistema está sano; las de negocio dicen si el servicio está sano. Son preguntas distintas: una API que responde 200 en 30 ms con cero alquileres iniciados a las ocho de la mañana está técnicamente perfecta y funcionalmente rota.

Todo se concentra en un componente, que es la práctica que mejor envejece:

Y su uso desde el servicio de dominio, que no conoce a Micrometer:

Tres decisiones de diseño merecen comentario. Un solo componente concentra los nombres de las métricas: sin él, las cadenas "ciclourbana.alquileres.iniciados" se dispersan por el código y aparecen las variantes (alquileres_iniciados, alquiler.iniciado) que rompen los cuadros de mando. Los nombres siguen la convención de Micrometer: minúsculas separadas por puntos y jerarquía de lo general a lo particular (ciclourbana.alquileres.iniciados), que cada sistema traduce a su propio estilo —Prometheus lo convertirá a ciclourbana_alquileres_iniciados_total—. Y la instrumentación no cambia el comportamiento: si registro fuera un SimpleMeterRegistry de pruebas, todo sigue funcionando igual.

Una advertencia sobre el Counter dentro del método: Counter.builder(...).register(registro) en cada invocación no crea un contador nuevo, porque register devuelve el existente si el nombre y las etiquetas coinciden. Es correcto, aunque tiene un pequeño coste de búsqueda; en un camino muy caliente conviene cachear los contadores en un Map por etiqueta.

Un Gauge no almacena valores: guarda una referencia al objeto que los tiene y una función para leerlo, y esa referencia es débil. Micrometer lo hace a propósito, para no impedir que el recolector de basura libere objetos que la aplicación ya no usa: una métrica nunca debe provocar una fuga de memoria.

La consecuencia es el error más desconcertante de todo Micrometer:

Esto funciona perfectamente durante minutos y luego la métrica empieza a devolver NaN. Cuando el GC pasa, el AtomicInteger —al que nadie apunta salvo la referencia débil del gauge— desaparece, y el medidor se queda sin fuente. Y el fallo es intermitente y depende de la presión de memoria, lo que lo convierte en el clásico «en desarrollo funcionaba».

La solución es la del apartado 7: el Map de campo mantiene la referencia fuerte mientras el componente viva. Otras dos formas correctas: usar registro.gauge("nombre", tags, objetoQueYaVive, funcion) sobre un objeto de larga vida, o Gauge.builder("cola.pendientes", laCola, Collection::size) sobre una colección que ya es un campo del bean.

Tres reglas más sobre gauges. Se registra una vez y luego solo se actualiza el valor: volver a registrar el mismo nombre con las mismas etiquetas devuelve el existente, pero registrarlo en un bucle es un olor a diseño. La función se invoca en el momento de la recogida, no cuando tú llamas: por eso debe ser barata y no debe lanzar excepciones —jamás un Gauge que ejecute una consulta a la base de datos, porque Prometheus la lanzaría cada 15 segundos—. Y un gauge que no cambia nunca no aporta nada: es una constante disfrazada de métrica.

Para la disponibilidad de Ribalta, el gauge se refresca desde la tarea programada de 07-03, que ya recorre las estaciones cada quince segundos, en lugar de calcularse en cada recogida.

Para instrumentar sin escribir código, Micrometer ofrece dos anotaciones basadas en aspectos. Requieren la dependencia de AOP y registrar los aspectos:

@Timed genera un Timer con etiquetas class, method y exception —esta última vale none cuando no hubo error, lo que permite separar la latencia de los éxitos de la de los fallos—. @Counted cuenta invocaciones con las mismas etiquetas.

Sus límites, que conviene tener claros antes de usarlas por todas partes. Sufren la trampa del proxy por cuarta vez en el curso: una llamada interna no se mide. No pueden etiquetar por datos del negocio: extraTags solo admite constantes, así que no hay forma de etiquetar por tipoTarifa recibido como argumento —para eso hace falta el código explícito del apartado 7—. Y añaden un aspecto por método anotado, con su coste de invocación.

El criterio de CicloUrbana: @Timed para instrumentación transversal y rápida —temporizar un servicio entero mientras se investiga algo—, y código explícito para las métricas de negocio que llevan etiquetas y que van a alimentar cuadros de mando permanentes.

Este apartado es el más técnico de la lección y el que más consecuencias tiene al escalar. En 09-01 quedó claro que el SLO se escribe en p95 y p99. La pregunta ahora es dónde se calculan esos percentiles, y hay dos respuestas incompatibles.

Por qué los percentiles del cliente no se pueden agregar. Es la consecuencia de aquella regla de 09-01: los percentiles no se promedian. Si la instancia 1 informa de p95 = 200 ms y la instancia 2 de p95 = 400 ms, el p95 real del servicio no es 300 ms, y no hay forma de calcularlo a partir de esos dos números: la información necesaria se perdió al calcularlos. Con tres réplicas en Kubernetes (08-04), esa gráfica de «p95» es sencillamente falsa.

Cómo lo resuelve el histograma. En lugar de un percentil, cada instancia exporta cuántas observaciones cayeron por debajo de cada umbral: 1.200 por debajo de 100 ms, 1.380 por debajo de 300 ms, y así. Esos recuentos sí se suman entre instancias, y a partir de la suma se interpola cualquier percentil con histogram_quantile (09-04). Se decide el percentil al consultar, no al instrumentar.

El precio es la cardinalidad: un histograma genera una serie por cubeta. Por eso existen los tres ajustes de arriba: slo añade cubetas exactamente en los umbrales que te importan —muy útil, porque permite después calcular directamente «qué porcentaje de peticiones bajó de 300 ms», que es la formulación literal de un objetivo de servicio—, y minimum-expected-value / maximum-expected-value acotan el rango, eliminando las cubetas absurdas por debajo de 10 ms o por encima de 10 s y reduciendo mucho el número de series.

La decisión de CicloUrbana: histogramas en las pocas métricas que sostienen los SLO (http.server.requests y la duración de alquileres) y nada de distribución en el resto. Activar percentiles-histogram para todo es una de las formas más rápidas de provocar el problema del apartado 6.

Cuando hay que corregir la instrumentación —propia o de una biblioteca que no controlas—, MeterFilter interviene en el registro de cada medidor:

Los cinco usos, en orden de utilidad real. Denegar métricas que no se usan reduce el tamaño de cada recogida —jvm.buffer y algunas de tomcat rara vez se miran—. maximumAllowableTags es la red de seguridad contra la explosión de cardinalidad: pasadas 100 estaciones distintas, deja de registrar nuevas series en lugar de tumbar Prometheus; es un salvavidas, no una excusa para etiquetar mal. maximumAllowableMetrics pone un techo global. renameTag y MeterFilter.commonTags permiten adaptar métricas de terceros a tu convención. Y la configuración de distribución por código aplica reglas a familias enteras de métricas por prefijo, algo que el YAML no permite.

Conviene distinguir los dos beans: MeterRegistryCustomizer se ejecuta una vez sobre el registro, mientras que el MeterFilter que instala se ejecuta para cada medidor que se registre. Y hay un orden que sorprende: los filtros se aplican en el orden en que se añaden, y un deny posterior no revoca un medidor ya registrado, así que los filtros deben instalarse antes de que la aplicación empiece a instrumentar —de ahí que se hagan en un @Bean y no en un @PostConstruct cualquiera—.

Con lo aprendido en 09-01 y 09-02, estas son las métricas que traducen aquellos diagnósticos puntuales en vigilancia continua:

La más rentable de todas es la penúltima combinada con jvm.gc.pause: memoria que sube y no baja tras las pausas es la firma de una fuga, y verla en una gráfica de un mes es infinitamente más fácil que en un volcado de heap. Y la primera, pending, es la que convierte el diagnóstico manual del ejercicio 1 de 09-01 en una alerta automática.

Hasta aquí hemos registrado métricas. Cuando en 09-06 haya que registrar trazas, aparecería el problema de instrumentar dos veces lo mismo. Spring Boot 3 lo resuelve con la Micrometer Observation API: se declara una observación y la infraestructura produce a la vez una métrica, un span de traza y, si se configura, una entrada de log.

La distinción entre lowCardinalityKeyValue y highCardinalityKeyValue es la regla del apartado 6 convertida en API, y es una de las mejores ideas de Micrometer: las claves de baja cardinalidad se convierten en etiquetas de la métrica y en atributos del span; las de alta cardinalidad van solo al span, donde no hacen daño. El modelo obliga a pensar en la cardinalidad al escribir el código, que es justo donde hay que pensarlo.

La versión declarativa necesita el aspecto correspondiente:

Hoy, con solo Micrometer Metrics en el classpath, esto produce un Timer idéntico al de @Timed. En 09-06, al añadir Micrometer Tracing, el mismo código empezará a producir spans sin tocar una línea. Esa es la razón para conocerlo ya: lo que se instrumente con la Observation API estará listo para la trazabilidad distribuida; lo que se instrumente con Timer a mano, no.

Como complemento, un ObservationHandler propio permite reaccionar a cada observación —por ejemplo, escribir una línea de log con su duración— y ObservationPredicate permite filtrar cuáles se registran, típicamente para ignorar /actuator/** y no medirse a uno mismo.

Instrumentar sin un método produce cientos de gráficas que nadie mira. Los dos métodos de referencia dicen qué mirar y son complementarios:

RED, para servicios (lo que ve el usuario): Rate (peticiones por segundo), Errors (proporción que falla) y Duration (distribución de la latencia).

USE, para recursos (lo que consume el sistema): Utilization (porcentaje de uso), Saturation (trabajo encolado esperando) y Errors (fallos del recurso).

La última fila es la más valiosa y la que casi nadie pone. Todos los indicadores técnicos pueden estar verdes mientras el servicio está roto: un despliegue que rompió el botón de alquilar en la app deja la API contestando 200 a las consultas de estaciones y cero alquileres iniciados. Una alerta sobre esa métrica de negocio detecta en cinco minutos lo que las técnicas no detectan nunca.

La implementación de estas alertas es trabajo de 09-04, con reglas en Prometheus y Alertmanager. Lo que se decide aquí es qué se mide y qué umbral se considera aceptable, y esa decisión es de producto tanto como de ingeniería.

Una métrica de negocio es comportamiento observable: si un refactor deja de incrementar el contador de alquileres, el cuadro de mando miente y nadie se entera. Se prueba con SimpleMeterRegistry, la implementación en memoria de Micrometer.

La segunda prueba es la joya: verifica que la referencia fuerte existe, que es precisamente el error que se manifiesta solo en producción y tras horas de ejecución. System.gc() es una sugerencia y no una garantía, pero en la práctica basta para que la prueba falle con la versión incorrecta del apartado 8.

En integración, @SpringBootTest con @AutoConfigureObservability levanta el registro real y permite comprobar que las métricas HTTP automáticas aparecen —por defecto, las pruebas desactivan la exportación—:

Etiquetar por identificador de usuario, por URI con identificadores o por identificador de traza. Es el error grave de la lección: explosión de cardinalidad que tumba primero a Prometheus y después a la aplicación, semanas después de haberse introducido. Lo que identifica a un individuo va al log o a la traza.

Perder el Gauge por la referencia débil. Funciona un rato y luego devuelve NaN. Guarda siempre una referencia fuerte en un campo del componente, y escribe la prueba con System.gc().

Usar un Counter para algo que baja. «Alquileres en curso» no es un contador: es un Gauge. Un contador que se decrementa rompe rate() y produce gráficas absurdas.

Creer que percentiles sirve con varias instancias. Los percentiles calculados en la JVM no se pueden agregar; con tres réplicas, esa gráfica es falsa. Se usan histogramas.

Activar percentiles-histogram para todas las métricas. Multiplica las series por diez. Solo en las que sostienen un SLO, y acotadas con minimum/maximum-expected-value.

Hacer trabajo dentro de la función de un Gauge. Se invoca en cada recogida, cada 15 segundos, para siempre. Una consulta a la base de datos ahí es una carga permanente que nadie relaciona con nada.

Medir solo lo técnico. Con todos los indicadores en verde el servicio puede estar roto. La métrica que avisa de un despliegue que rompió el alquiler es ciclourbana.alquileres.iniciados cayendo a cero.

Consejo: centraliza los nombres de métricas en un componente o en constantes. Los nombres son un contrato con los cuadros de mando y las alertas de 09-04; un cambio de nombre rompe paneles en silencio. Y sigue la convención de Micrometer —minúsculas con puntos, prefijo de aplicación—, dejando que cada exportador la traduzca.

Consejo: usa la Observation API para lo nuevo. Cuesta lo mismo que un Timer y en 09-06 producirá spans sin tocar el código.

Consejo: pon las etiquetas comunes (application, entorno, instancia) desde el primer día. Añadirlas después obliga a reescribir todas las consultas y a perder la continuidad de las gráficas.

Para cada necesidad del ayuntamiento de Ribalta, indica el tipo de medidor, el nombre, las etiquetas —justificando su cardinalidad— y si necesita histograma: (a) cuántas bicicletas hay ahora mismo en mantenimiento, por taller (hay 2 talleres); (b) cuántos cobros ha rechazado la pasarela, distinguiendo el motivo (SALDO, TARJETA_CADUCADA, TECNICO); (c) cuánto tarda la importación nocturna del ayuntamiento, sabiendo que dura entre 20 y 50 minutos y que se quiere vigilar mientras se ejecuta; (d) el importe de cada alquiler facturado, para poder responder «¿cuál es el importe mediano y el p95?»; (e) cuántas veces cada ciudadano ha alquilado este mes.

Un compañero ha añadido esta instrumentación. Tres semanas después, Prometheus consume 12 GB de memoria, /actuator/prometheus tarda 8 segundos en responder y la gráfica de bicicletas disponibles muestra huecos. Encuentra los tres problemas, explica el síntoma de cada uno y escribe la versión corregida.

El ayuntamiento pide un acuerdo de nivel de servicio. Define los SLI y SLO de CicloUrbana siguiendo RED y USE: elige cuatro indicadores de servicio y tres de recursos, di con qué métrica de Micrometer se calcula cada uno, propón un umbral y un periodo de evaluación, e indica cuáles de esos umbrales deberían despertar a alguien de madrugada y cuáles no. Justifica la configuración de management.metrics.distribution que hace posible medirlos.

Solución 1.

(a) Bicicletas en mantenimiento por taller: Gauge, ciclourbana.bicicletas.mantenimiento, etiqueta taller (2 valores: cardinalidad mínima). Es un valor que sube y baja, luego no es un contador. Sin histograma —los gauges no tienen distribución—. Cuidado con la referencia fuerte del apartado 8: un Map<String, AtomicInteger> como campo, refrescado desde la tarea programada, y nunca una consulta a la base de datos dentro de la función del gauge.

(b) Cobros rechazados: Counter, ciclourbana.cobros.rechazados, etiqueta motivo con 3 valores fijos del enumerado. Solo sube y lo que interesa es su ritmo, que rate() extraerá en 09-04. La etiqueta debe salir de un enumerado, nunca del mensaje de error de la pasarela: un texto libre devuelto por un tercero es cardinalidad ilimitada disfrazada.

(c) Importación nocturna: LongTaskTimer, ciclourbana.importacion.duracion. Es el caso que justifica su existencia: un Timer normal no publicaría nada durante los 40 minutos que dura y solo registraría el resultado al terminar, con lo que sería imposible saber si está en marcha o colgada. El LongTaskTimer publica active_tasks y duration de las tareas en curso, permitiendo alertar de «lleva más de 60 minutos». Complemento útil: un Gauge con la marca de tiempo de la última ejecución correcta, para detectar que no se ha ejecutado.

(d) Importe facturado: DistributionSummary, ciclourbana.alquiler.importe, baseUnit("euros"), con publishPercentileHistogram() porque la pregunta pide explícitamente mediana y p95 y hay varias instancias. No es un Timer porque no mide tiempo. Etiqueta razonable: tarifa (3 valores). Conviene acotar con minimum-expected-value: 0.5 y maximum-expected-value: 50 para no generar cubetas inútiles.

(e) Alquileres por ciudadano y mes: ninguna métrica. Es cardinalidad ilimitada —una serie por ciudadano— y además no es una pregunta de monitorización sino de negocio, con la fila del alquiler ya guardada en PostgreSQL: se responde con SELECT usuario_id, count(*) ... GROUP BY usuario_id. La regla del apartado 6 en su forma más pura: las métricas responden «cuántos» agregado, no «quién».

Solución 2.

Problema 1 — etiqueta usuario de cardinalidad ilimitada. Una serie por ciudadano; con 50.000 usuarios, 50.000 series de un solo contador. Síntoma: memoria de Prometheus disparada y consultas lentas. Es la causa principal de los 12 GB.

Problema 2 — etiqueta uri con el identificador del alquiler. Cardinalidad infinita: una serie nueva por cada alquiler creado, para siempre, y ninguna de ellas se reutiliza jamás. Síntoma: /actuator/prometheus devolviendo megabytes y tardando 8 segundos, porque su tamaño crece linealmente con el número de alquileres históricos. Es incluso peor que el anterior, porque no tiene techo.

Problema 3 — Gauge registrado en cada petición sobre un objeto temporal. Dos fallos en una línea: se registra dentro del método, así que se intenta crear un medidor por petición, y el AtomicInteger no tiene referencia fuerte, así que el GC lo libera y el gauge devuelve NaN. Síntoma: los huecos en la gráfica. Además, contarLibres() en el camino de la petición añade una consulta a cada alquiler.

Versión corregida:

Las decisiones: la instrumentación se va al servicio, con metricas.alquilerIniciado(tipoTarifa, idEstacion) y sus dos etiquetas de baja cardinalidad; la URI y el estado ya los aporta http.server.requests con la plantilla, de modo que el contador manual de peticiones sobraba por completo; y el gauge de bicicletas libres se registra una vez en MetricasCicloUrbana, con su referencia fuerte y actualizado desde la tarea programada de 07-03. Como red de seguridad, se añade el MeterFilter.maximumAllowableTags(...) del apartado 11, que habría convertido esta caída en una métrica truncada.

Solución 3.

Indicadores de servicio (RED), medidos sobre http.server.requests:

Indicadores de recursos (USE):

Qué despierta y qué no. El criterio es doble: el usuario lo está sufriendo ahora y hay algo que hacer. Por eso despiertan la tasa de error, la latencia del endpoint crítico sostenida, la ausencia de alquileres en hora punta y el pool saturado —que es el aviso temprano de una caída completa—. No despiertan las pausas de GC ni la utilización de hilos: son causas, no síntomas, y su lugar es un aviso en horario laboral. Es el principio que se desarrollará en 09-04: alertar sobre síntomas, no sobre causas, porque cada alerta que no exige acción inmediata erosiona la credibilidad de todas las demás.

Configuración necesaria:

Histograma y no percentiles, porque con tres réplicas los percentiles calculados en cada JVM no se pueden agregar y darían una cifra falsa (apartado 10). Las cubetas de slo en 300 ms y 800 ms permiten responder directamente «qué porcentaje de peticiones cumplió el objetivo», que es la formulación literal del SLO y la que se llevará al informe mensual del ayuntamiento. Y el acotado entre 10 ms y 5 s evita decenas de cubetas inútiles, manteniendo la cardinalidad bajo control.

CicloUrbana ya no solo se deja preguntar: se mide sola y continuamente. Tienes claros los tres pilares de la observabilidad y qué responde cada uno —métricas para detectar, trazas para localizar, logs para entender—, y entiendes Micrometer como la fachada que hace que tu código registre contadores sin saber quién los recogerá, con MeterRegistry inyectable como un bean más. Sabes elegir entre los seis tipos de medidor con criterios que resuelven las dudas reales: contador para «cuántas veces» y gauge para «cuánto hay ahora», Timer para operaciones del programa y DistributionSummary para magnitudes de negocio, LongTaskTimer para lo que hay que vigilar mientras ocurre.

Conoces el catálogo de métricas que existen sin escribir código —con http.server.requests como la más valiosa del sistema— y sabes consultarlas por /actuator/metrics con ?tag=, con la limitación de que ahí no hay historia. Y tienes grabada la regla de oro de esta lección: la cardinalidad de una etiqueta debe ser baja y acotada; tarifa y estacion sí, idUsuario, la URI con identificadores y el trazaId jamás, porque lo que identifica a un individuo pertenece a un log o a una traza y no a una métrica.

Has instrumentado la red de Ribalta con MetricasCicloUrbana: contadores de alquileres iniciados y finalizados por tarifa, un gauge de bicicletas disponibles por estación —con la referencia fuerte que evita el NaN de la referencia débil, y su prueba con System.gc()—, un Timer del cálculo de tarifa y un DistributionSummary de la duración de los trayectos, todo tras una fachada que deja al dominio sin conocer Micrometer. Sabes cuándo @Timed y @Counted bastan y dónde están sus tres límites. Entiendes la diferencia que más importa al escalar: los percentiles calculados en la JVM no se agregan entre instancias y los histogramas sí, con slo, minimum-expected-value y maximum-expected-value para que esa potencia no se pague con una explosión de series. Y sabes corregir y proteger la instrumentación con MeterFilter, incluida la red de seguridad de maximumAllowableTags.

Por último, tienes los números que vigilar en el pool, la base de datos y las cachés de 09-02; la Observation API como el modelo unificado que convierte la cardinalidad en API (lowCardinalityKeyValue frente a highCardinalityKeyValue) y que en 09-06 producirá spans sin tocar el código; y los métodos RED y USE convertidos en SLI y SLO concretos, incluida la fila que casi nadie pone y que detecta un servicio roto con todo en verde: alquileres iniciados = 0 en hora punta.

Queda el problema que ha estado presente todo el rato: todo esto vive en memoria y muere con el proceso. Cada despliegue de 08-05 borra las métricas; /actuator/metrics no tiene historia; no hay gráficas, no hay comparación con la semana pasada y, sobre todo, no hay una sola alerta. Los SLO del apartado 14 están definidos pero no vigilados por nadie. La siguiente lección, Uso de Prometheus y Grafana, cierra ese hueco: el modelo de recogida por consulta, el formato de /actuator/prometheus, PromQL de verdad —rate, sum by, histogram_quantile sobre las cubetas que acabamos de configurar—, el cuadro de mando de CicloUrbana panel a panel y las reglas de alerta que convierten estos números en una llamada de teléfono cuando de verdad hace falta.