¶ SIMAPPE MONITOR LOGS
¶ Spring Boot Admin Server para el Ecosistema Simappe / Nebula
Version: 1.0.0
Fecha: 29 de Abril, 2026
Estado: NORMATIVO - Componente operativo del stack
Arquitecto: Carlos Alberto Torres Camargo
Componente: simappe-monitor-logs v1.0.1
¶ 1. PROPOSITO
simappe-monitor-logs es un microservicio Spring Boot Admin (SBA) que centraliza la observabilidad operativa de todos los microservicios registrados en Eureka del ecosistema Simappe / Nebula. Provee una interfaz web unica autenticada para inspeccionar estado vivo, logs en tiempo real, niveles de log dinamicos, threads, environment, beans, mappings y health detallado por instancia.
Complementariedad: SBA NO reemplaza a Prometheus + Grafana (metricas time-series). SBA cubre el estado vivo por instancia y los logs; Grafana cubre tendencias historicas y agregaciones.
¶ 1.1. Casos de uso principales
| Caso de uso | Tab SBA | Endpoint base |
|---|---|---|
| Ver logs en vivo de un servicio | Logfile | /actuator/logfile |
| Cambiar nivel de log en runtime sin reiniciar | Loggers | /actuator/loggers |
| Diagnosticar hilos bloqueados / deadlocks | Threads | /actuator/threaddump |
| Inspeccionar variables de entorno y propiedades efectivas | Environment | /actuator/env |
| Ver beans cargados y dependencias | Beans | /actuator/beans |
| Ver mappings REST por servicio | Mappings | /actuator/mappings |
| Ver health detallado por componente (DB, Mongo, Kafka, Redis) | Details | /actuator/health |
| Limpiar caches en linea | Caches | /actuator/caches |
¶ 2. COORDENADAS DEL PROYECTO
| Propiedad | Valor |
|---|---|
| groupId | com.catcsoft.simappe.server |
| artifactId | SimappeMonitorLogs |
| version | 1.0.1 |
| package | com.catcsoft.simappe.server.monitor |
| container_name | simappe-monitor-logs |
| Puerto | 8088 |
| Imagen registry | 10.110.0.2:5000/simappe/simappe-monitor-logs:latest |
| Repo principal (origin) | https://github.com/carlosatc/simappe-monitor-logs |
| Repo Centrica (centrica) | https://gitlab.centricasoluciones.com/simappe/core/simappe-monitor-logs |
¶ 3. STACK TECNOLOGICO
| Categoria | Tecnologia | Version | Proposito |
|---|---|---|---|
| Runtime | Java | 25 | Lenguaje de ejecucion |
| Framework | Spring Boot | 3.5.14 | Framework principal |
| Admin | Spring Boot Admin Server | 3.5.4 | UI consolidada de Actuator |
| Cloud | Spring Cloud | 2025.0.0 | Eureka client (descubrimiento) |
| Seguridad | Spring Security | 6.x (managed) | Form login + Basic Auth |
| Cache | Caffeine | Latest | Cache local |
| Observabilidad | Micrometer Prometheus | Latest | Metricas formato Prometheus |
¶ 4. ARQUITECTURA
¶ 4.1. Modelo de descubrimiento via Eureka
Flujo:
- Cada microservicio se registra en Eureka con su
homePageUrl,healthCheckUrl, ymetadata-map.management.context-path. - SBA tiene
spring.boot.admin.discovery.enabled: truey consume el catalogo de Eureka cada 30s. - Para cada instancia descubierta, SBA construye la URL del actuator:
homePageUrl + management.context-path. - SBA polea
/actuator/*periodicamente y mantiene el estado en memoria. - El cliente (browser o
curl) accede a la UI con autenticacion (form login o Basic Auth).
¶ 4.2. Anotaciones clave
@SpringBootApplication
@EnableAdminServer // Habilita los endpoints SBA y la UI
@EnableDiscoveryClient // Registra este servicio en Eureka y consume el registro
public class SimappeMonitorLogsApplication { ... }
¶ 5. ESTRUCTURA DEL PROYECTO
simappe-monitor-logs/
├── src/
│ ├── main/
│ │ ├── java/com/catcsoft/simappe/server/monitor/
│ │ │ ├── SimappeMonitorLogsApplication.java # @EnableAdminServer + @EnableDiscoveryClient
│ │ │ └── SecurityConfig.java # Form login + Basic Auth + whitelist health/info
│ │ └── resources/
│ │ ├── application.yml # Base: nombre + perfil activo
│ │ ├── application-localhost.yml # Standalone (Eureka en localhost)
│ │ ├── application-local.yml # Docker compose local
│ │ ├── application-dev.yml # Centrica DEV (nodo-01)
│ │ ├── application-prod.yml # Produccion endurecida
│ │ ├── banner.txt # ASCII banner
│ │ └── META-INF/additional-spring-configuration-metadata.json
│ └── test/java/...
│ └── SimappeMonitorLogsApplicationTests.java
├── Dockerfile # Multi-stage Eclipse Temurin 25 JRE Alpine + CDS
├── deploy-centrica-dev.sh # Build + push registry local + deploy nodo-01
├── deploy-repsy-dev.sh # Build + push Repsy + deploy
├── deploy-ecr.sh # Build + push AWS ECR + deploy vps-catcsoft
├── pom.xml # Maven, Java 25, SBA 3.5.4
├── mvnw / mvnw.cmd # Maven wrapper
└── CLAUDE.md # Guia para asistente IA
¶ 6. CONFIGURACION
¶ 6.1. Perfiles disponibles
| Perfil | Hostname Eureka | Hostname instancia | Caso de uso |
|---|---|---|---|
localhost (default) |
localhost:8761 |
localhost |
Desarrollo aislado fuera de Docker |
local |
eureka-server:8761 |
simappe-monitor-logs |
Docker compose en maquina dev |
dev |
simappe-eureka-server:8761 |
simappe-monitor-logs |
Centrica DEV (nodo-01, red dev-network) |
prod |
simappe-eureka-server:8761 |
simappe-monitor-logs |
Produccion (logs reducidos, health.show-details: when-authorized) |
Activacion via env: APP_PROFILE=dev.
¶ 6.2. Variables de entorno
| Variable | Default | Proposito |
|---|---|---|
APP_PROFILE |
localhost |
Perfil Spring activo |
PORT |
8088 |
Puerto HTTP |
EUREKA_HOST |
depende del perfil | Host del Eureka server |
EUREKA_INSTANCE_HOST |
depende del perfil | Hostname con que el servicio se registra |
SBA_USER |
nebula |
Usuario para acceder a la UI |
SBA_PASSWORD |
centrica2026! (dev), CHANGE_ME_IN_PROD (prod) |
Password |
¶ 6.3. Endpoints actuator expuestos
management:
endpoints:
web:
exposure:
include:
- health
- info
- metrics
- prometheus
endpoint:
health:
show-details: always # when-authorized en prod
¶ 7. SEGURIDAD
¶ 7.1. Modelo de autenticacion
SecurityConfig.java implementa una cadena con dos modos:
- Form login para acceso desde navegador (
/logincon redireccion post-auth). - Basic Auth para acceso programatico (curl, scripts, integraciones).
¶ 7.2. Whitelist (sin auth)
| Path | Razon |
|---|---|
/actuator/health/** |
Healthcheck de Docker (wget --spider) y registro Eureka |
/actuator/info |
Lectura de metadata por Eureka client |
<adminContextPath>/assets/** |
Recursos estaticos de la UI |
<adminContextPath>/login |
Pagina de login |
¶ 7.3. Cualquier otra ruta requiere autenticacion
http.authorizeHttpRequests(auth -> auth
.requestMatchers(
new AntPathRequestMatcher(adminContextPath + "/assets/**"),
new AntPathRequestMatcher(adminContextPath + "/login"),
new AntPathRequestMatcher("/actuator/health/**"),
new AntPathRequestMatcher("/actuator/info")
).permitAll()
.anyRequest().authenticated()
)
¶ 7.4. CSRF
CSRF activado con cookie XSRF-TOKEN (HttpOnly false para que el frontend SBA pueda leerla). Excluidas:
POST /instances(registro de instancias por SBA Client si se usara push mode)DELETE /instances/*/actuator/**
¶ 7.5. Servicios monitoreados (sin auth)
Por simplicidad, los actuators de los microservicios monitoreados quedan sin auth dentro de dev-network. SBA es el unico endpoint protegido. Si en el futuro se requiere proteger los actuators de los servicios, hay que:
- Agregar Spring Security a cada servicio.
- Configurar SBA con
spring.boot.admin.instance-auth.default-user-nameydefault-password.
¶ 8. INTEGRACION CON LOS SERVICIOS DEL STACK
¶ 8.1. Configuracion global en SimappeConfig
Los servicios monitoreados deben exponer endpoints actuator extendidos. Esto se logra globalmente en simappeconfig (config repo) en cada application-{profile}.yml:
#-------------------------------------------------------------------
# SPRING BOOT ACTUATOR (GLOBAL) - exposed for SBA + Prometheus
#-------------------------------------------------------------------
management:
endpoints:
web:
base-path: /actuator
exposure:
include: "*"
endpoint:
health:
show-details: always
probes:
enabled: true
#-------------------------------------------------------------------
# LOGGING FILE (required for /actuator/logfile)
#-------------------------------------------------------------------
logging:
file:
name: logs/${spring.application.name}.log
#-------------------------------------------------------------------
# EUREKA METADATA - tells SBA how to reach actuator (handles context-path)
#-------------------------------------------------------------------
eureka:
instance:
metadata-map:
management.context-path: ${server.servlet.context-path:}/actuator
health-check-url-path: ${server.servlet.context-path:}/actuator/health
status-page-url-path: ${server.servlet.context-path:}/actuator/info
¶ 8.2. Por que management.context-path es critico
Servicios con server.servlet.context-path (ej. nebula-accounting-core en /nebula-accounting-core) tienen el actuator en /<context-path>/actuator/* y NO en /actuator/*. Sin metadata-map.management.context-path, SBA construye URLs invalidas (apunta a /actuator/* en el host pelado) y reporta DOWN o no descubre endpoints.
La expresion ${server.servlet.context-path:}/actuator resuelve correctamente para los dos casos:
| Servicio | context-path |
URL actuator construida |
|---|---|---|
simappe-gateway-server |
(vacio) | http://host:port/actuator |
simappe-config-server |
(vacio) | http://host:port/actuator |
simappe-monitor-logs |
(vacio) | http://host:port/actuator |
simappe-admin |
/simappe-admin |
http://host:port/simappe-admin/actuator |
simappe-client |
/simappe-client |
http://host:port/simappe-client/actuator |
simappe-oauth2-server |
/simappe-oauth2-server |
http://host:port/simappe-oauth2-server/actuator |
nebula-accounting-core |
/nebula-accounting-core |
http://host:port/nebula-accounting-core/actuator |
nebula-masters |
/nebula-masters |
http://host:port/nebula-masters/actuator |
¶ 9. DESPLIEGUE
¶ 9.1. Dockerfile
Multi-stage con Eclipse Temurin Java 25 JRE Alpine y entrenamiento CDS para arranque rapido. Patron identico al de simappe-eureka-server y simappe-config-server.
¶ 9.2. Compose (nodo-01: Centrica DEV)
Vive en business/server/docker-compose.yml junto a config-server, eureka, gateway y oauth2. Patron de healthcheck HTTP wget al actuator/health (puerto fijo 8088, sin context-path).
simappe-monitor-logs:
image: 10.110.0.2:5000/simappe/simappe-monitor-logs:latest
container_name: simappe-monitor-logs
ports:
- "8088:8088"
environment:
- APP_PROFILE=dev
- SPRING_MAIN_LAZY_INITIALIZATION=true
- SPRING_THREADS_VIRTUAL_ENABLED=true
# Override credenciales si se desea:
# - SBA_USER=...
# - SBA_PASSWORD=...
networks:
- dev-network
restart: unless-stopped
deploy:
resources:
limits:
memory: 512M
depends_on:
simappe-eureka-server:
condition: service_healthy
healthcheck:
test: ["CMD-SHELL", "wget -q --spider http://localhost:8088/actuator/health || exit 1"]
interval: 30s
timeout: 10s
retries: 5
start_period: 300s
logging:
driver: json-file
options:
max-size: "10m"
max-file: "3"
¶ 9.3. Scripts de deploy
| Script | Destino | Detalle |
|---|---|---|
deploy-centrica-dev.sh |
Registry local 10.110.0.2:5000 + nodo-01 | Build mvn + docker build + push + ssh deploy |
deploy-repsy-dev.sh |
Repsy + 192.168.122.131 | Para entornos catc legacy |
deploy-ecr.sh |
AWS ECR + vps-catcsoft | Para entornos productivos AWS |
¶ 9.4. Workflow estandar (Centrica DEV)
# 1. Cambios en simappe-monitor-logs
cd backend/simappe-monitor-logs
# editar codigo / config
# 2. Verificar build local
./mvnw clean package -DskipTests
# 3. Auditar antes de commit (cwd, branch, scope)
pwd && git status --short && git diff --stat
# 4. Commit + push (origin GitHub primero, centrica GitLab despues)
git add -A
git commit -m "..."
git push origin develop
git push centrica develop
# 5. Deploy
./deploy-centrica-dev.sh
# 6. Si el SSH del script falla por timeout (IP publica),
# completar manualmente desde maquina con alias nodo-01:
ssh nodo-01 'cd ~/docker/compose/business/server && docker compose pull simappe-monitor-logs && docker compose up -d simappe-monitor-logs'
¶ 10. COMO CONSULTAR
¶ 10.1. UI web
URL en Centrica DEV: http://nodo-01:8088
- Redirige a
/login(form login) - Usuario:
nebula - Password:
centrica2026!(default; overridable por env)
Una vez autenticado, el dashboard muestra todos los servicios registrados en Eureka como hexagonos con su numero de instancias y version. Click en un servicio para entrar a la vista por instancia.
Captura tomada en Centrica DEV (nodo-01) con usuario
nebula. Cada hexagono representa una aplicacion logica; el numero "15m" indica el tiempo desde el ultimo cambio de estado.
¶ 10.2. API REST programatica
# Listar aplicaciones (Basic Auth, JSON explicito)
curl -u "nebula:centrica2026!" \
-H "Accept: application/json" \
http://nodo-01:8088/applications
# Inspeccionar una instancia
curl -u "nebula:centrica2026!" \
http://nodo-01:8088/instances/<instance-id>
¶ 10.3. Health publico (sin auth)
# Para healthcheck Docker o probes externos
curl http://nodo-01:8088/actuator/health
¶ 11. LIMITACIONES CONOCIDAS
¶ 11.1. Cache tab vacio en servicios
/actuator/caches solo muestra org.springframework.cache.CacheManager beans estandar. Caffeine en los servicios Simappe registra el CaffeineCacheManager correctamente, pero los caches son lazy: solo aparecen cuando se llama por primera vez a un metodo @Cacheable. Hasta entonces el manager existe vacio.
Solucion opcional: pre-registrar los nombres de cache via
cacheManager.setCacheNames(List.of("..."))en elCacheConfigdel servicio.
¶ 11.2. Redis no aparece en Caches
TenantRedisCache (de SimappeCommons) extiende AbstractTenantCacheManager, una interfaz custom que NO implementa org.springframework.cache.CacheManager de Spring. Por diseno, no aparece en SBA. Para que aparezca habria que wrappear como RedisCacheManager estandar (cambio en SimappeCommons).
¶ 11.3. Servicios con PORT=0 (puerto aleatorio)
Servicios como nebula-accounting-core, simappe-admin, simappe-client, nebula-masters usan ${PORT:0} (puerto aleatorio JVM). Eureka registra el puerto correcto y SBA lo usa. El healthcheck Docker NO puede usar HTTP en estos contenedores (no conoce el puerto), por eso usa smoke check pgrep -f java. Vease HEALTHCHECK_PATTERN_DOCKER (si existe; sino, ver compose).
¶ 11.4. Push del SSH en deploy script
El script deploy-centrica-dev.sh hace SSH a 200.118.43.29:2202 (IP publica). Desde algunas redes ese tramo cae en timeout. Si pasa: build + push de imagen al registry SI completaron; basta finalizar manualmente con ssh nodo-01 'docker compose pull && docker compose up -d simappe-monitor-logs'.
¶ 12. REFERENCIAS EXTERNAS
¶ 12.1. Spring Boot Admin (codecentric)
simappe-monitor-logs es una implementacion del proyecto open source Spring Boot Admin mantenido por codecentric AG. SBA es un wrapper alrededor de los endpoints Spring Boot Actuator que provee una UI Vue.js consolidada para inspeccionar multiples instancias.
| Recurso | URL | Uso |
|---|---|---|
| Repositorio GitHub | https://github.com/codecentric/spring-boot-admin | Codigo fuente, issues, releases |
| Documentacion oficial | https://docs.spring-boot-admin.com/ | Guia de configuracion, propiedades, integraciones |
| Maven Central (server) | de.codecentric:spring-boot-admin-starter-server |
Dependencia usada en este componente |
| Compatibilidad | Spring Boot 3.5.x ↔ SBA 3.5.x | Las versiones se alinean al major.minor de Spring Boot |
| Licencia | Apache 2.0 | Compatible con uso comercial interno |
¶ 12.2. Recursos relacionados
- Spring Boot Actuator: https://docs.spring.io/spring-boot/docs/current/reference/html/actuator.html — endpoints que SBA consume.
- Netflix Eureka: https://github.com/Netflix/eureka — service registry usado para descubrimiento.
- Micrometer: https://micrometer.io/ — metricas que aparecen en la pestana Metrics de SBA.
¶ 13. DOCUMENTACION RELACIONADA
| Documento | Ubicacion | Relacion |
|---|---|---|
| Arquitectura Simappe-Nebula | 03-Simappe-Stack | Stack completo donde encaja SBA |
| Comandos de Ejecucion | 03-Simappe-Stack | Comandos generales del stack |
| Estructura de Proyecto y Paquetes | 03-Simappe-Stack | Patron de organizacion de codigo |
| Flujo Descubrimiento de Servicio | 03-Simappe-Stack/flujos | Mecanica de Eureka que SBA aprovecha |
¶ HISTORIAL DE CAMBIOS
| Version | Fecha | Autor | Descripcion |
|---|---|---|---|
| 1.0.0 | 2026-04-29 | Carlos Torres | Creacion del documento. Cubre v1.0.1 del componente, instalado en nodo-01 con auth nebula / centrica2026! y descubrimiento global via Eureka metadata. |
| 1.0.1 | 2026-04-29 | Carlos Torres | Fix sintaxis mermaid 8.8.2 en diagrama de descubrimiento. |
| 1.0.2 | 2026-04-29 | Carlos Torres | Agregar seccion 12 Referencias Externas con enlaces a Spring Boot Admin (codecentric), Actuator, Eureka y Micrometer. |
| 1.0.3 | 2026-04-29 | Carlos Torres | Agregar screenshot del dashboard SBA en seccion 10.1 (imagenes/sba-dashboard-aplicaciones.png). |