health y info en Actuator

1. health y info como conjunto mínimo

Si abres Actuator por primera vez, es fácil caer en dos estados extremos: o «wow, abriré todo, que sea», o «qué va, esto es claramente para DevOps, yo todavía no». Para no caer en ninguna de las dos trampas, es útil empezar con dos endpoints que dan beneficio incluso a un pequeño servicio: health y info. El primero responde a la pregunta muy corta «¿está vivo el servicio?», el segundo a «¿qué es este servicio?». Juntos forman la «tarjeta de visita operativa» mínima de la aplicación, que es conveniente comprobar tanto visualmente como de forma automática.

Imagina que tu servicio es un café. health es el cartel en la puerta «Abierto/Cerrado», y info es «Cómo se llama el café y qué vendes aquí». Ni el menú, ni la contabilidad, ni la receta secreta de la salsa los colgamos en la puerta. Pero «abierto/cerrado» y «cómo te llamas» — eso sí.

Para fijar la diferencia, aquí hay una tabla pequeña (puedes tenerla mentalmente cada vez que la mano se estire a «bueno, pongamos absolutamente todo en info»):

Y otro matiz importante que a menudo descompone el sistema nervioso del principiante: un endpoint puede existir, pero no ser accesible por HTTP debido a la política de exposición. Es decir, «existe en la aplicación», pero «en el navegador da 404». Esto no es misticismo ni «Actuator no funciona», sino simplemente una configuración separada de publicación. Por ahora mantenemos el foco en el significado y contenido de health/info.

2. /actuator/health: comprobación del servicio

Cuando decimos «comprobar el servicio», el desarrollador principiante a menudo lo hace por vieja costumbre: abre el navegador, pulsa en GET /api/catalog/courses y si llega JSON — «bueno, entonces está vivo». Esto, por supuesto, funciona, pero escala mal: un endpoint de negocio puede caer por razones no relacionadas con la salud de la aplicación, además puede estar desactivado, requerir parámetros o cambiar según el contrato. health es un punto especial que tiene una única tarea: decir honesta y brevemente si todo está bien desde el punto de vista de la «viabilidad» del servicio.

En su forma más básica, health se ve muy modesto: devuelve un JSON con el estado. En el caso simple verás:

{
  "status": "UP"
}

Y ese «UP» ya es más útil de lo que parece. No es «el controlador devolvió una respuesta», es exactamente «Actuator considera que la aplicación está viva». Es decir, comienzas a separar «el servicio se levantó como plataforma» de «nuestra lógica de dominio funcionó».

Un poco más terrenal para el desarrollador, esto ayuda en dos situaciones típicas. La primera — cambiaste la configuración, el servicio arrancó, el puerto escucha, pero tienes dudas «¿está realmente bien o solo veo Tomcat?». La segunda — el servicio no cayó completamente, sino que «bajo el capó» algo no está bien, y quieres una señal rápida antes de meterte en los logs y el debug.

Si quieres verlo manualmente, normalmente se ve así:

# -s (silent) elimina el ruido superfluo, para que en la salida solo estén los datos
# jq . formatea bonito el JSON, para que sea más fácil verificar la estructura visualmente
curl -s http://localhost:8080/actuator/health | jq .
# {
#   "status": "UP"
# }

Sí, usamos curl y jq porque es la forma más rápida de asegurarse de que el endpoint devuelve lo que esperas. También se puede en el navegador, pero en la terminal empiezas a pensar más rápido «endpoint = datos», no «endpoint = página».

3. Detalles de health: show-details

Después del primer «status: UP» a menudo surge en el principiante un deseo natural: «¿Y si health lo explicara todo? Que escriba qué beans se levantaron, qué properties ganaron, y ojalá también la lista de cursos en el catálogo». Este deseo es comprensible, pero peligroso. health es una puerta, no un tour por la sala de servidores. Si empiezas a revelar detalles demasiado pronto, corres el riesgo de hacer que el diagnóstico sea ruidoso o sensible en cuanto a datos.

Por lo tanto, un comienzo sensato es mantener health corto, y activar los detalles solo cuando sea realmente necesario y solo donde sea apropiado. En Actuator esto se controla con la configuración show-details. En una línea base segura (especialmente si el endpoint potencialmente puede ser accesible no solo para ti) configuramos never.

Ejemplo de configuración en src/main/resources/application.yaml:

management:
  endpoint:
    health:
      # Configuración básica para una salud «segura»: solo estado sin detalles
      show-details: never

Con esta opción, health sigue siendo breve. Es conveniente incluso localmente: primero te acostumbras a percibir health como un «semáforo», y luego como un «informe».

A veces en el perfil local se quiere ver más. Esto es normal, pero hazlo de forma consciente y vincúlalo a perfiles para no arrastrar accidentalmente la «locuacidad» a un entorno más estricto. Por ejemplo, en src/main/resources/application-local.yaml se puede hacer así:

management:
  endpoint:
    health:
      # Localmente se puede ser más hablador para diagnosticar problemas más rápido
      show-details: always

En este modo, la respuesta se vuelve más larga y puede contener «componentes» (partes de la comprobación) y su estado. Más o menos así (la forma puede diferir un poco, pero el significado es el mismo):

{
  "status": "UP",
  "components": {
    "diskSpace": {
      "status": "UP"
    },
    "ping": {
      "status": "UP"
    }
  }
}

Observa un efecto psicológicamente importante: comienzas a ver que la «salud» no es un UP/DOWN mágico, sino la agregación de varias comprobaciones. Pero, una vez más, al inicio del curso es mejor mantener esto en el entorno local de pruebas, no convertirlo en «mostramos todo a todos».

4. /actuator/info: tarjeta de visita de la aplicación

Si health es «¿está vivo?», entonces info es «¿quién eres?». El error más común con info es: el desarrollador lo percibe como «bueno, es información, entonces pongamos aquí la configuración, variables de entorno, tokens, URLs, y todo lo que no esté clavado». Como resultado, info se convierte en un «README público + volcado aleatorio de entrañas». Y luego alguien se sorprende de por qué la seguridad es un dolor.

El modelo correcto para info es: un JSON corto que ayuda a una persona (o sistema de monitoreo) a entender rápidamente qué servicio está levantado, qué versión tiene y en qué modo funciona. Es decir, información neutral y estable.

Aquí es fácil confundir dos cosas diferentes: qué debe contener info y si está abierto por HTTP. Incluso si la tarjeta de visita está bien armada, por la URL se puede ver un 404 si el endpoint aún no se ha publicado hacia el exterior. Por lo tanto, a continuación nos centramos precisamente en el payload de info y en qué datos es apropiado poner allí.

En catalog-service, los buenos candidatos para info suelen ser el nombre de la aplicación, su versión (incluso si por ahora la escribes a mano como cadena), una descripción corta, y también algunos modos muy neutrales como «catálogo de solo lectura». La idea es simple: info debe ser útil, incluso si lo abres después de un mes y ya has olvidado qué estabas configurando.

En Spring Boot, info se construye a partir de «contribuidores» (contributors). A nivel básico del curso, es importante entender una cosa concreta: puedes poner datos bajo las claves info.* en la configuración, y ellos (con el contribuidor env habilitado) aparecerán en la respuesta de info como un JSON estructurado.

Se habilita así:

management:
  info:
    env:
      # Permitimos tomar datos del bloque info.* y devolverlos en /actuator/info
      enabled: true

Y los propios datos se pueden definir así:

info:
  app:
    # Nombre del servicio (lo que quieres ver en la «tarjeta de visita»)
    name: "catalog-service"
    # Descripción corta y neutral — sin secretos ni datos de dominio
    description: "Read-only catalog of courses"
    # Versión útil para diagnóstico: «¿qué build está ejecutándose ahora?»
    version: "1.0.0"

Si todo está conectado como debe, la respuesta de /actuator/info se verá más o menos así:

{
  "app": {
    "name": "catalog-service",
    "description": "Read-only catalog of courses",
    "version": "1.0.0"
  }
}

Es como una credencial de conferencia: nombre, rol, tal vez empresa. No tu correspondencia en Slack ni la contraseña del Wi‑Fi.

5. Configuración de health y info en catalog-service

Ahora viene lo mejor: no solo «aprendimos sobre los endpoints», sino que los integraremos en nuestro servicio de catálogo concreto, que ya vive en modo config-first. La idea es muy simple: health que se mantenga corto (sin detalles por defecto), e info devolverá una tarjeta de visita clara, y no hardcodeada en código Java, sino construida desde la configuración. Porque ya que estamos haciendo un Boot-template, hagámoslo honesto: cambia la configuración — cambia el «pasaporte».

En src/main/resources/application.yaml se puede añadir (o dejar así) el siguiente bloque:

management:
  endpoint:
    health:
      # En la configuración base ocultamos detalles para que el endpoint sea seguro por defecto
      show-details: never
  info:
    env:
      # Permitimos devolver info.* en /actuator/info
      enabled: true

info:
  app:
    # Tomamos el nombre de spring.application.name para no duplicar y no desincronizar
    name: ${spring.application.name}
    # La tarjeta de visita debe ser corta y neutral
    description: "Read-only catalog of courses"
    # Ejemplo de nombre «legible para humanos» del catálogo desde tus propiedades personalizadas
    catalog-title: ${app.catalog.title}
    # Por ahora se puede mantener la versión como cadena, luego se puede automatizar
    version: "1.0.0"

Aquí hay dos puntos que son especialmente útiles para el principiante.

El primer punto — los placeholders del tipo ${spring.application.name} y ${app.catalog.title}. Ya hemos trabajado con configuración, así que esto es una continuación de la misma idea: info no es un «JSON manual», también es una capa que se puede vincular con tus fuentes de propiedades. Resulta bastante elegante: cambias spring.application.name o app.catalog.title — y info refleja automáticamente la realidad.

El segundo punto — el límite. No ponemos conscientemente «todo lo que sea». Por ejemplo, no ponemos la lista completa de cursos. No ponemos la configuración completa. No ponemos variables de entorno. info debe mantenerse corto y seguro.

Si deseas un poco más de comodidad en el perfil local, puedes distinguir local de otros entornos. Por ejemplo, en application-local.yaml puedes añadir un campo «environment» para que en el JSON se vea directamente dónde estás:

info:
  app:
    # Una marca explícita del entorno ayuda a no adivinar qué perfil está activo
    environment: "local"

Entonces /actuator/info devolverá adicionalmente environment, y no tendrás que adivinar «¿estoy en local o accidentalmente activé dev?». Es un detalle, pero ahorra muy bien tiempo y nervios.

6. Errores típicos al trabajar con health y info

Cuando empiezas a usar Actuator, los errores no suelen ser «sintácticos», sino «semánticos». Es decir, la aplicación arranca, el endpoint responde, pero accidentalmente te construyes (o a tus colegas) una superficie de diagnóstico incómoda o insegura. A continuación — los errores típicos más frecuentes que se encuentran precisamente en el nivel básico, cuando se quiere ver «más cosas útiles» rápidamente.

Error n.º 1: esperar que health sea un informe de depuración completo.
health es un indicador rápido de estado, no un relato de «por qué no funcionó mi filtro track=SPRING». Si percibes health como un diagnóstico universal, o bien te decepcionarás constantemente («¿y los detalles?»), o bien activarás los detalles para siempre y harás que el endpoint sea demasiado hablador. Es mejor mantener health como una señal corta, y activar la profundidad de forma consciente y dosificada.

Error n.º 2: activar show-details: always «para que sea cómodo» y olvidar que esto puede ir más allá del entorno local.
Localmente, un health detallado es realmente agradable. Pero si lo mantienes activado en todos los perfiles, te acostumbras gradualmente a la «locuacidad» y puedes dejarlo accidentalmente donde ya no es apropiado. Los perfiles no existen por belleza: son convenientes para fijar que localmente se pueden tener más detalles, y en un entorno más estricto, menos.

Error n.º 3: convertir info en un «volcado de todo el mundo de configuración».
info es una tarjeta de visita, no «aquí tienes mi application.yaml, disfruta». Si en info aparecen valores aleatorios del entorno, URLs, flags internos y todo lo demás, el endpoint deja de ser claro y seguro. Además, luego tú mismo no podrás entender rápidamente qué es importante y qué es simplemente «ruido por ruido».

Error n.º 4: olvidar management.info.env.enabled y luego sorprenderse de que info.* «no funciona».
Una situación muy típica: añadiste en application.yaml el bloque info: ..., reiniciaste la aplicación, abriste /actuator/info, y allí está vacío (o casi vacío). Surge la sensación de «escribí algo mal». En realidad, simplemente no habilitaste el contribuidor env en info. Es mejor verlo como otra lección de Boot: muchas cosas no están «mágicamente activadas», sino que se controlan mediante configuración.

Error n.º 5: mezclar «identidad de la aplicación» y «datos de dominio» en info.
info no debe convertirse en una «mini-API del catálogo», donde se encuentre, por ejemplo, la lista de cursos, el número de cursos destacados o detalles de filtrado. Estas cosas pertenecen al API de dominio (/api/catalog/...) o a una diagnosis separada, pero no a la tarjeta de visita del servicio. Una buena regla: si los datos cambian a menudo y son entidades de negocio — no tienen lugar en info.