Configuración de Spring Boot Starter

Cómo integrar Axelix Spring Boot Starter en una aplicación Spring Boot para que Axelix Master pueda descubrirla, leer su estado y actuar sobre ella.

Esta página muestra cómo integrar Axelix Spring Boot Starter en una aplicación Spring Boot para que Axelix Master pueda descubrirla, leer su estado y actuar sobre ella, tanto desde la interfaz como mediante el servidor MCP (Model Context Protocol) integrado en Master, que expone los mismos datos a los agentes de IA. Elija el módulo de starter que corresponda a la versión principal de Boot, exponga los endpoints Actuator de Axelix (automático desde Axelix 1.2.0), comparta la clave de firma JWT con Master e indique a Master dónde encontrar la instancia.

Antes de empezar

Algunos datos que conviene tener claros antes de copiar los fragmentos siguientes.

  • Tres módulos de starter, uno por versión principal de Spring Boot. Elija el que coincida con la versión de Boot que ya utiliza la aplicación:
    • com.axelixlabs:axelix-spring-boot-2-starter: Spring Boot 2.7+ (un mínimo obligatorio, no solo la versión probada; compilado y probado con 2.7.18, Spring Cloud 2021.0.9, JDK 11 como mínimo).
    • com.axelixlabs:axelix-spring-boot-3-starter: Spring Boot 3.x (compilado y probado con 3.0.13, Spring Cloud 2022.0.4, JDK 17 como mínimo).
    • com.axelixlabs:axelix-spring-boot-4-starter: Spring Boot 4.x (compilado y probado con 4.0.6, Spring Cloud 2025.1.0, JDK 17 como mínimo).
  • Qué aporta el starter: un conjunto de endpoints Actuator específicos de Axelix (axelix-metadata, axelix-beans, axelix-loggers, …), un filtro de autorización basado en JWT que los protege y un componente opcional de autorregistro que anuncia esta instancia a Master.
  • El plugin de compilación de Axelix también es obligatorio: además de la dependencia del starter, aplique el plugin de compilación de Axelix para Gradle o Maven. Incorpora las coordenadas de compilación (groupId/artifactId/version) al artefacto, y Master identifica cada aplicación por esas coordenadas: una instancia compilada sin el plugin no puede registrarse. Consulte ¿Qué es el plugin de compilación de Axelix? y Configuración del plugin de compilación.
  • Dos consumidores de los mismos datos: Master sirve la interfaz de Axelix en / y un servidor MCP en /api/mcp (controlado por axelix.master.mcp-server.enabled, activado por defecto). Ambos leen los endpoints Actuator expuestos por el starter, por lo que integrarlo hace visible la instancia para los usuarios de la interfaz y para los clientes MCP sin configuración adicional en el starter.
  • Qué necesita Master para comunicarse con la instancia: acceso HTTP a la ruta base de Actuator de la aplicación (por defecto /actuator), los endpoints de Axelix expuestos mediante management.endpoints.web.exposure.include y una clave de firma JWT idéntica a la configurada en Master. Consulte Autenticación: JWT para el lado de Master.
  • Dos formas de que Master encuentre la instancia:
    • Descubrimiento automático desde Master: Master explora su entorno (actualmente, Services de Kubernetes) y sondea por sí mismo el endpoint Actuator. El starter solo debe exponer los endpoints; no hay nada más que configurar.
    • Autorregistro: el starter envía una señal de actividad a Master a intervalos fijos. Utilícelo cuando Master no pueda explorar el entorno de la instancia (otra red, ausencia de integración de plataforma o máquinas virtuales convencionales).

Aplicaciones reactivas (WebFlux)

PublicadoDisponible desde la versión: 1.3.0

Desde Axelix 1.3.0, los tres starters funcionan en aplicaciones reactivas basadas en Spring WebFlux, además de en aplicaciones servlet (Spring MVC). El starter detecta qué pila web utiliza la aplicación, por lo que no hay nada adicional que añadir ni configurar: la dependencia, el plugin de compilación y las propiedades de esta página son iguales para ambas. Los endpoints de Axelix y la autorización JWT que los protege funcionan igual, incluso cuando Actuator utiliza un management.server.port independiente.

Una función sigue siendo exclusiva de servlet. La supervisión de transacciones, y con ella las páginas Transaction Control y Entities Map, no está disponible en aplicaciones WebFlux.

Añadir la dependencia

Declare la coordenada del starter correspondiente a la versión principal de Boot.

Los fragmentos siguientes utilizan la versión más reciente, 1.3.1.

build.gradle.kts
dependencies {
    implementation("com.axelixlabs:axelix-spring-boot-4-starter:1.3.1")
}

El starter también depende de Spring Boot Actuator. Si la aplicación no incluye ya spring-boot-starter-actuator, añádalo junto al starter.

El plugin de compilación es un paso independiente

Aplicar el plugin de compilación de Axelix es obligatorio para todos los servicios gestionados, pero se explica en su propia sección. Consulte ¿Qué es el plugin de compilación de Axelix? y Configuración del plugin de compilación.

Dependencias transitivas

El starter está diseñado para añadir lo mínimo posible al classpath. Se compila contra todas las tecnologías con las que se integra —Spring Boot, Actuator, Spring Kafka, Micrometer, Caffeine, Jackson—, pero no las incorpora: el starter utiliza lo que ya tiene la aplicación. Las únicas bibliotecas que incorpora de forma transitiva son:

DependenciaMotivo
org.slf4j:slf4j-apiRegistro de eventos. Ya está presente en todas las aplicaciones Spring Boot.
io.jsonwebtoken:jjwt-api, jjwt-impl, jjwt-jacksonVerificación del JWT que Master envía en cada solicitud.

El objetivo es reducir esta lista. El starter es el componente de Axelix que se ejecuta dentro de sus servicios, y cada biblioteca que incorpora es un elemento adicional del classpath que debe analizarse, parchearse y mantenerse compatible con el resto de la aplicación. La postura del equipo central de Axelix es que el starter no debería tener ninguna dependencia externa, y estamos eliminando las restantes paso a paso. Puede seguir el progreso en axelixlabs/axelix#1748.

JsonPath ya no se incluye

PublicadoDisponible desde la versión: 1.2.0

Hasta Axelix 1.1.x inclusive, el starter también incorporaba com.jayway.jsonpath:json-path, aunque nunca lo utilizaba. Desde Axelix 1.2.0, esa dependencia se ha eliminado: el primer paso hacia el starter sin dependencias descrito en axelixlabs/axelix#1748.

Si la aplicación utiliza JsonPath en su propio código y solo lo obtenía mediante el starter de Axelix, declárelo explícitamente al actualizar. Spring Boot gestiona su versión, por lo que no es necesario especificarla:

build.gradle.kts
dependencies {
    implementation("com.jayway.jsonpath:json-path")
}

Las pruebas no se ven afectadas: spring-boot-starter-test incorpora JsonPath por sí mismo.

JSpecify ya no se incluye

PublicadoDisponible desde la versión: 1.3.0

Hasta Axelix 1.2.x inclusive, el starter también incorporaba org.jspecify:jspecify. El starter utiliza JSpecify solo para sus anotaciones de nulabilidad y únicamente lo necesita durante la compilación. Desde Axelix 1.3.0, la dependencia se ha eliminado, como siguiente paso hacia el starter sin dependencias descrito en axelixlabs/axelix#1748.

El starter sigue funcionando sin JSpecify en el classpath, porque la JVM ignora las anotaciones cuyas clases no están disponibles durante la ejecución. En Spring Boot 4 no cambia nada, ya que el propio Spring Framework 7 depende de JSpecify.

Si su código utiliza las anotaciones de JSpecify y solo las obtenía mediante el starter de Axelix, declare la dependencia explícitamente al actualizar. Spring Boot 2 y 3 no gestionan su versión, por lo que debe especificarla:

build.gradle.kts
dependencies {
    implementation("org.jspecify:jspecify:1.0.0")
}

Endpoints Actuator

Desde Axelix 1.2.0 no hay nada que configurar manualmente: al iniciar la aplicación, el starter añade sus propios endpoints Actuator a management.endpoints.web.exposure.include, por lo que Master puede acceder a ellos sin configuración adicional. En versiones anteriores, el starter no lo hace y los endpoints deben enumerarse manualmente. Consulte Exponer los endpoints en Axelix anterior a 1.2.0.

Qué expone el starter

El starter expone los siguientes endpoints:

EndpointFinalidadDesde
axelix-metadata obligatorioMetadatos del servicio; el primero que Master sondea1.0.0
axelix-pingActualizaciones de estado, memoria y transacciones que Master consulta para instancias ya conocidas y descubiertas automáticamente. Necesario para el sondeo; las instancias autorregistradas envían actualizaciones mediante señales de actividad.1.3.0
axelix-detailsInformación resumida de la instancia1.0.0
axelix-beansBeans del contexto1.0.0
axelix-cachesCachés (cuando hay un CacheManager)1.0.0
axelix-conditionsInforme de condiciones de autoconfiguración1.0.0
axelix-configprops@ConfigurationProperties1.0.0
axelix-envEntorno y fuentes de propiedades1.0.0
axelix-feign heredadoClientes Feign (cuando Feign está en el classpath). Eliminado en 1.3.0, véase más abajo1.0.0
axelix-gcRecolección de basura1.0.0
axelix-heap-dumpVolcado del heap1.0.0
axelix-loggersNiveles de registro1.0.0
axelix-logsEntradas de registro recientes1.3.0
axelix-metricsMétricas1.0.0
axelix-scheduled-tasksTareas programadas1.0.0
axelix-thread-dumpVolcado de hilos1.0.0
axelix-dependenciesSBOM de dependencias1.2.0

La columna Desde indica la primera versión del starter de Axelix que incluyó el endpoint. 1.0.0 es la primera versión de Axelix, por lo que un endpoint marcado con 1.0.0 existe desde el principio. Una versión marcada como próxima aún no se ha publicado: el endpoint estará disponible en la siguiente versión de Axelix, tanto si es menor como si es principal.

Los endpoints que no se aplican a la aplicación permanecen inactivos: el starter solo activa cada uno cuando se cumplen sus requisitos (por ejemplo, axelix-caches nunca se activa sin un CacheManager).

Desde Axelix 1.2.0, los endpoints nativos health e info ya no son necesarios, por lo que el starter nunca los expone por sí mismo (antes de 1.2.0 Axelix dependía de ellos y el starter forzaba la exposición de ambos). Solo se exponen los endpoints que se enumeren en management.endpoints.web.exposure.include y los de Axelix; añada health e info a la lista cuando los necesite, incluido el endpoint health que Spring Boot expondría por defecto en otras circunstancias.

Se ha eliminado el endpoint axelix-feign

PublicadoDisponible desde la versión: 1.3.0

Hasta Axelix 1.2.x inclusive, los starters de Spring Boot 3 y Spring Boot 4 también aportaban un endpoint axelix-feign que enumeraba los clientes Spring Cloud OpenFeign de la aplicación. Axelix Master nunca lo utilizó para mostrar información y solo se conservaba como un resto de las primeras etapas del proyecto. Desde Axelix 1.3.0, el endpoint se ha eliminado de los starters junto con todo el código de Master que podía invocarlo.

No hay nada que hacer al actualizar. La única diferencia visible es que /actuator/axelix-feign ya no existe en un servicio con el starter 1.3.0 o posterior; si alguna herramienta propia llama directamente a esa URL, recibirá un 404. Si enumera manualmente los endpoints de Axelix en management.endpoints.web.exposure.include y axelix-feign está entre ellos, puede quitarlo de la lista; dejarlo no causa problemas.

Añadir endpoints propios

Si necesita endpoints Actuator propios, enumere solo esos: el starter combina su lista con la suya propia en lugar de sustituirla.

management:
  endpoints:
    web:
      exposure:
        include:
          - prometheus

Como resultado, se exponen prometheus y todos los endpoints de Axelix.

También se admite el valor *: se expone todo y el starter no modifica la lista.

Exponer los endpoints en Axelix anterior a 1.2.0

Versiones anterioresSolo necesario antes de la versión: 1.2.0. En versiones posteriores, omita esta sección.

Los starters anteriores a 1.2.0 no añaden por sí mismos sus endpoints a la lista de exposición, por lo que cada endpoint de Axelix que desee que lea Master debe incluirse manualmente en management.endpoints.web.exposure.include. Como mínimo, exponga axelix-metadata —sin él, la instancia nunca aparece en Master— y, en la práctica, el conjunto completo para que cada sección de la interfaz tenga datos que mostrar. Esas versiones del starter exponen forzosamente health e info por sí mismas, por lo que no es necesario enumerarlos:

management:
  endpoints:
    web:
      exposure:
        include:
          - axelix-metadata
          - axelix-beans
          - axelix-caches
          - axelix-conditions
          - axelix-configprops
          - axelix-details
          - axelix-env
          - axelix-gc
          - axelix-heap-dump
          - axelix-loggers
          - axelix-metrics
          - axelix-scheduled-tasks
          - axelix-thread-dump

Estas versiones del starter también aportan el endpoint heredado axelix-feign. Se omite de la lista de forma intencionada: Master nunca lo lee y el endpoint se elimina en Axelix 1.3.0. Véase más arriba.

Exportar métricas de Axelix mediante Micrometer

El endpoint Actuator axelix-metrics proporciona los datos de la interfaz de Axelix. Además, los starters de Spring Boot pueden publicar un pequeño conjunto de medidores específicos de Axelix en el MeterRegistry de Micrometer de la propia aplicación.

Esta vía de exportación se activa automáticamente si hay un bean MeterRegistry. No existe ninguna propiedad adicional de Axelix para ello. El starter registra estos medidores:

MedidorTipoEtiquetasSignificado
axelix_transaction_durationTimerclass, methodDuración de cada ejecución @Transactional supervisada. El temporizador también publica los percentiles 0.5, 0.95 y 0.99.
axelix_transaction_queriesCounterclass, methodNúmero total de consultas SQL ejecutadas dentro de transacciones supervisadas.
axelix_transaction_external_callsCounterclass, methodNúmero total de llamadas externas (por ejemplo RestTemplate) realizadas dentro de transacciones supervisadas.
axelix_cache_requestsCountercache, resultNúmero total de consultas a la caché registradas por las cachés ampliadas por Axelix.
axelix_cache_enabledGaugecacheEstado actual de cada caché ampliada durante la ejecución: 1 si está activada, 0 si está desactivada.

Estos medidores complementan los endpoints Actuator utilizados por la interfaz, no los sustituyen. La interfaz sigue leyendo axelix-metrics y axelix-caches. La información inicial sobre transacciones se incluye en los metadatos de registro; las actualizaciones posteriores utilizan axelix-ping cuando Master sondea starters desde 1.3.0, o señales de actividad enviadas por las instancias autorregistradas. No hay ningún endpoint de Actuator específico para transacciones; véase Supervisión de transacciones.

Compartir la clave de firma JWT con Master

Todos los endpoints Actuator de Axelix están protegidos por JwtAuthorizationFilter. El filtro espera un token HS256, HS384 o HS512 firmado con la misma clave que utiliza Master, por lo que ambos deben coincidir en el algoritmo y el secreto. Utilice el mismo valor establecido en axelix.master.auth.jwt.signing-key de Master.

Desde el starter 1.3, Master autoriza al usuario autenticado antes de llamar al servicio. El starter recibe un JWT de usuario técnico de corta duración con sujeto AXELIX.MASTER, sin los roles ni permisos del usuario. Verifica la identidad de Master, la firma y la caducidad del token. Los starters anteriores siguen comprobando los permisos del usuario, por lo que Master vuelve a emitir el token del usuario con nombres de permisos heredados para ellos. El descubrimiento inicial utiliza un token de compatibilidad aceptado por ambas versiones; consulte Cómo funciona el descubrimiento.

axelix:
  sbs:
    auth:
      jwt:
        algorithm: HMAC512
        signing-key: ${AXELIX_JWT_SIGNING_KEY}

Desde Axelix 1.3, axelix.sbs.auth.jwt.duration ya no se utiliza. Puede eliminarlo de la configuración. El starter emite un nuevo JWT de usuario técnico para cada solicitud de registro y señal de actividad. Cada token tiene una duración fija de un minuto para limitar el tiempo durante el que puede utilizarse un token robado. No se necesita una propiedad de sustitución y la duración no es configurable.

La clave de firma compartida entre Master y todos los servicios supervisados es un secreto sensible. Inyéctela mediante una variable de entorno, un archivo montado o un gestor de secretos, no mediante un YAML bajo control de versiones.

Ejecución sin clave de firma

PublicadoDisponible desde la versión: 1.2.0

Desde Axelix 1.2.0, algorithm y signing-key son opcionales. Si no se establecen, el starter utiliza HMAC512 y la misma clave integrada que Master utiliza por defecto, por lo que el servicio se conecta a un Master con configuración predeterminada sin configurar claves. Mientras se utiliza la clave integrada, el starter registra una advertencia al iniciar.

La clave integrada es públicamente conocida. Cualquiera que pueda acceder a los endpoints Actuator del servicio puede firmar un token con ella e invocar los endpoints de Axelix, por ejemplo para leer el entorno o realizar un volcado del heap. Establezca su propia axelix.sbs.auth.jwt.signing-key, igual que en Master, antes de utilizar Axelix más allá de una prueba local.

Permitir que Master encuentre la instancia

Elija una de las dos vías siguientes. En la práctica son mutuamente excluyentes: el autorregistro solo añade latencia si Master ya puede explorar el entorno.

Opción A: descubrimiento automático desde Master

Si Master se ejecuta dentro de un clúster de Kubernetes junto a los servicios, la configuración más sencilla es dejar que Master explore el espacio de nombres en busca de Services y sondee /actuator/axelix-metadata en cada uno. No se necesita configuración adicional en el starter aparte de exponer los endpoints Actuator y compartir la clave de firma JWT. Configure la exploración desde Master mediante axelix.master.discovery.auto.*; consulte Descubrimiento: descubrimiento automático en la página de Master. Para conocer qué hace Master en cada exploración, consulte Cómo funciona el descubrimiento.

Opción B: autorregistro

Si Master no puede explorar el entorno de la instancia —otro clúster, una máquina virtual convencional o una red aislada—, active el autorregistro en el starter. La instancia envía entonces señales de actividad con su URL de Actuator a Master a intervalos fijos. Master acepta el envío en POST /api/internal/service/register, que es también la dirección que debe indicarse en axelix.sbs.discovery.master-url. Desde Axelix 1.3.0, el starter solo envía este registro completo una vez y luego pasa a señales ligeras, que se dirigen a un endpoint junto a master-url. Para conocer el ciclo completo, consulte Cómo funciona el descubrimiento.

axelix:
  sbs:
    discovery:
      self-registration: true
      master-url: http://master.internal:2935/api/internal/service/register
      instance-actuator-url: http://my-app.internal:8080/actuator
      instance-name: orders-service
      heartbeat-interval: 15s

Algunos detalles que suelen causar confusión:

  • instance-actuator-url es la URL del servicio tal como Master accederá a él desde su propia red, incluida la ruta base configurada de Actuator, normalmente /actuator.
  • master-url es la URL completa, incluido /api/internal/service/register. El starter la utiliza sin modificarla para sus envíos. Master escucha en 2935 por defecto desde Axelix 1.2.0; antes de esa versión, el puerto predeterminado era 8080. Consulte General.
  • instance-name es la etiqueta que Master muestra para esta instancia en la interfaz y en las respuestas MCP. Elija un nombre que se mantenga entre reinicios y réplicas, normalmente el del servicio, no el del pod.
  • Master acepta el autorregistro sin configuración adicional (axelix.master.discovery.self-registration.enabled es true por defecto); establézcalo en false si desea rechazar las señales de actividad. Master elimina una instancia tras axelix.master.discovery.self-registration.eviction.heartbeat-timeout de silencio (45s por defecto), por lo que debe mantener heartbeat-interval bastante por debajo de ese tiempo.

Enmascarar valores sensibles de propiedades

Los endpoints de Axelix axelix-env y axelix-configprops devuelven valores de propiedades a Master. Para evitar que se lean secretos sin los permisos adecuados, Master enmascara los valores para los usuarios que no tienen el permiso correspondiente. Las mismas reglas se aplican a ambos endpoints. Configure las claves de propiedades sensibles en el starter:

axelix.sbs.endpoints.config.sanitized-properties

  • Lista vacía (valor predeterminado): todos los valores devueltos por axelix-env y axelix-configprops se sustituyen por ****** para llamantes sin el permiso correspondiente. El valor predeterminado es conservador de forma intencionada: la protección no requiere activación explícita.
  • Lista no vacía: solo se enmascaran las claves enumeradas; todo lo demás se devuelve sin enmascarar a cualquier llamante. Utilícela si el valor predeterminado conservador resulta demasiado restrictivo y desea enmascarar solo claves concretas (contraseñas, tokens o claves de firma).

El permiso se comprueba por endpoint:

  • axelix-env: el permiso environment.values:read permite al llamante ver los valores sin enmascarar.
  • axelix-configprops: el permiso config-properties.values:read permite al llamante ver los valores sin enmascarar.

Los roles integrados ADMIN y SUPER_ADMIN de Master conceden ambos permisos. VIEWER y EDITOR siempre pasan por la función de enmascaramiento. Consulte Roles y permisos para ver la matriz completa.

axelix:
  sbs:
    endpoints:
      config:
        sanitized-properties:
          - database.password
          - spring.datasource.password
          - jwt.signing-key
          - axelix.sbs.auth.jwt.signing-key

Las opciones estándar de enmascaramiento de Spring Boot Actuator —management.endpoint.env.show-values, management.endpoint.env.keys-to-sanitize y sus equivalentes configprops— no se consultan.

Referencia de configuración

Todas las propiedades del starter pertenecen al espacio de nombres axelix.sbs.*.

Desactivar el starter

PublicadoDisponible desde la versión: 1.2.0

axelix.sbs.enabled es el interruptor global de todo el starter. Es true por defecto, por lo que añadir la dependencia basta para activar todo lo descrito en esta página. Si se establece en false, se desactiva toda la autoconfiguración de Axelix: sin endpoints Actuator de Axelix, sin filtro de autorización JWT, sin señales de autorregistro, sin medidores Micrometer y sin supervisión de transacciones. La aplicación se inicia como si el starter no estuviera en el classpath, aunque la propia dependencia permanece en la compilación.

Utilice esta opción si desea desactivar Axelix en un entorno concreto —por ejemplo, localmente o en un perfil de pruebas— sin mantener un conjunto separado de dependencias. También permite descartar rápidamente al starter al investigar problemas de inicio.

axelix:
  sbs:
    enabled: false

La propiedad se lee una vez, durante el inicio. Por tanto, modificarla requiere reiniciar la aplicación.

Con el starter desactivado, Master deja de ver la instancia: fallan los sondeos de descubrimiento automático a /actuator/axelix-metadata y cesan las señales de autorregistro, por lo que la instancia desaparece de la interfaz y de las respuestas MCP.

PropiedadValor predeterminadoDescripción
axelix.sbs.enabledtrueInterruptor global de todo el starter. Establézcalo en false para desactivar toda la autoconfiguración de Axelix. Se comporta de forma idéntica en los starters de Spring Boot 2, 3 y 4.

Autenticación: JWT

PropiedadValor predeterminadoDescripción
axelix.sbs.auth.jwt.algorithmHMAC512 (1.2.0+; obligatorio antes)Algoritmo de firma. Uno de HMAC256, HMAC384 o HMAC512. Debe coincidir con axelix.master.auth.jwt.algorithm de Master.
axelix.sbs.auth.jwt.signing-keyclave integrada (1.2.0+; obligatoria antes)Secreto compartido utilizado para verificar los tokens emitidos por Master y firmar las señales de autorregistro. Debe coincidir con la clave de firma de Master.
axelix.sbs.auth.jwt.duration5mSolo se utiliza antes de 1.3 para la duración del token de autorregistro. Desde 1.3, esta opción no tiene efecto y puede eliminarse. Se emite un nuevo token de usuario técnico por solicitud con una duración fija de un minuto.

Autorregistro

El autorregistro está desactivado por defecto (axelix.sbs.discovery.self-registration=false): manténgalo así cuando Master pueda encontrar la instancia mediante descubrimiento automático desde Master.

Cuando axelix.sbs.discovery.self-registration=true, las siguientes propiedades pasan a ser obligatorias:

  • axelix.sbs.discovery.master-url
  • axelix.sbs.discovery.instance-actuator-url
  • axelix.sbs.discovery.instance-name

El receptor de estas señales en Master —endpoint, tiempo de espera para expulsión y programación del barrido de expulsión— se documenta en la página de Master, en Descubrimiento: autorregistro. La clave de firma JWT configurada en axelix.sbs.auth.jwt.signing-key debe coincidir con axelix.master.auth.jwt.signing-key de Master; de lo contrario, las señales se rechazan con 401.

PropiedadValor predeterminadoDescripción
axelix.sbs.discovery.self-registrationfalseInterruptor principal. Establézcalo en true para activar el autorregistro; mantenga false para depender del descubrimiento automático desde Master.
axelix.sbs.discovery.master-url(sin establecer) obligatoriaURL completa del endpoint de autorregistro de Master, por ejemplo http://master:2935/api/internal/service/register. Obligatoria cuando self-registration=true.
axelix.sbs.discovery.instance-actuator-url(sin establecer) obligatoriaURL de este servicio accesible desde Master, incluida la ruta base configurada de Actuator (normalmente /actuator). Obligatoria cuando self-registration=true.
axelix.sbs.discovery.instance-name(sin establecer) obligatoriaNombre visible en la interfaz de Axelix y en las respuestas MCP. Obligatorio cuando self-registration=true.
axelix.sbs.discovery.heartbeat-interval15sIntervalo entre señales de actividad. Debería ser menor que el heartbeat-timeout de expulsión de Master.

Enmascaramiento de valores en endpoints

PropiedadValor predeterminadoDescripción
axelix.sbs.endpoints.config.sanitized-properties(lista vacía)Claves de propiedades cuyos valores se enmascaran como ****** para llamantes sin environment.values:read (en axelix-env) o config-properties.values:read (en axelix-configprops). Una lista vacía significa que se enmascaran todos los valores. Consulte Enmascarar valores sensibles de propiedades para conocer las reglas de coincidencia.

Gestión de cachés

PublicadoDisponible desde la versión: 1.2.0

La gestión de cachés proporciona los datos de la página Caches y los medidores axelix_cache_*: el starter envuelve cada bean CacheManager de la aplicación en un proxy que registra las consultas a la caché y permite activar, desactivar y vaciar cachés durante la ejecución, y expone esos datos mediante el endpoint Actuator axelix-caches. Está activada por defecto cuando el starter está en el classpath.

Establezca axelix.sbs.cache.management.enabled en false para desactivarla por completo: sin proxies de CacheManager, sin endpoint axelix-caches y sin medidores de caché. Los beans CacheManager quedan entonces exactamente como los definió la aplicación.

axelix:
  sbs:
    cache:
      management:
        enabled: false
PropiedadValor predeterminadoDescripción
axelix.sbs.cache.management.enabledtrueInterruptor principal de la gestión de cachés. Establézcalo en false para desactivar toda la autoconfiguración de gestión de cachés. Se comporta de forma idéntica en los starters de Spring Boot 2, 3 y 4.

Con la gestión de cachés desactivada, la página Caches de Master no tiene datos que mostrar para esta instancia y las herramientas MCP de caché fallan para ella.

Entradas de registro

PublicadoDisponible desde la versión: 1.3.0

El endpoint axelix-logs sirve las entradas de registro más recientes de la aplicación para poder leerlas sin acceder al equipo anfitrión. El starter conserva estas entradas en memoria desde el inicio de la aplicación. Cuando el búfer está lleno, cada nueva entrada desplaza a la más antigua. Como el búfer reside en memoria, vuelve a estar vacío después de un reinicio.

Por defecto, el starter conserva las últimas 1000 entradas. Aumente axelix.sbs.logs.max-entries si un servicio con mucha actividad genera tantos registros que 1000 entradas solo cubren unos segundos. Redúzcalo si hay poca memoria, porque cada entrada conservada permanece en el heap.

axelix:
  sbs:
    logs:
      max-entries: 5000
PropiedadValor predeterminadoDescripción
axelix.sbs.logs.max-entries1000Número máximo de las entradas de registro más recientes que el starter conserva en memoria. Debe ser mayor que 0.

El starter comprueba el valor una vez iniciada la aplicación. Si es 0 o negativo, el inicio falla con una IllegalArgumentException cuyo mensaje es axelix.sbs.logs.max-entries must be positive.

Supervisión de transacciones

La supervisión de transacciones proporciona los datos de la página Transaction Control y los medidores asociados: envuelve los métodos @Transactional, crea un proxy de la fuente de datos para contar consultas, limpia la pila de transacciones por solicitud y registra el integrador N+1 de Hibernate. El registro inicial incluye la información recopilada. Las actualizaciones posteriores utilizan axelix-ping cuando Master sondea starters desde 1.3.0, o señales de actividad enviadas por las instancias autorregistradas; los starters anteriores siguen proporcionando los metadatos de registro completos. Exponga axelix-ping para sondear starters desde 1.3.0; no se necesita ningún endpoint adicional específico para transacciones. La supervisión de transacciones está activada por defecto cuando el starter está en el classpath.

La supervisión de transacciones solo funciona en aplicaciones servlet (Spring MVC). En una aplicación reactiva (WebFlux), el starter no la activa, independientemente del valor de la propiedad. Consulte Aplicaciones reactivas (WebFlux).

Establezca axelix.sbs.transaction.monitoring.enabled en false para desactivarla por completo: sin posprocesadores de beans, sin proxies de la fuente de datos, sin filtro de limpieza y sin integrador de Hibernate. Utilícelo para reducir la sobrecarga asociada, para descartar interferencias al investigar la configuración de la fuente de datos o de Hibernate, o simplemente si no utiliza la función.

axelix:
  sbs:
    transaction:
      monitoring:
        enabled: false
PropiedadValor predeterminadoDescripción
axelix.sbs.transaction.monitoring.enabledtrueInterruptor principal de la supervisión de transacciones. Establézcalo en false para desactivar toda la autoconfiguración de supervisión de transacciones. Se comporta de forma idéntica en los starters de Spring Boot 2, 3 y 4.

Desactivar la supervisión de transacciones también desactiva la detección de paginación en memoria descrita a continuación, ya que forma parte de la misma autoconfiguración.

Detección de paginación en memoria

Detecta la paginación en memoria de Hibernate causada por utilizar setFirstResult/setMaxResults junto con la carga de una colección.

Por defecto, la supervisión de transacciones registra un appender que intercepta las advertencias de Hibernate (HHH000104 en Hibernate 5.x y HHH90003004 en Hibernate 6.x–7.3.x). El starter elige el appender que corresponde al sistema de registro activo de la aplicación, por lo que la detección funciona tanto con Logback como con Log4j2:

  • Logback: el starter registra com.axelixlabs.axelix.sbs.spring.core.persistence.hibernate.pagination.LogbackInMemoryPaginationAppender. Es el caso de una configuración estándar de Spring Boot, cuyo sistema de registro es Logback.
  • Log4j2: si la aplicación utiliza Log4j2 (normalmente tras añadir spring-boot-starter-log4j2 y excluir el starter predeterminado de Logback), el starter registra com.axelixlabs.axelix.sbs.spring.core.persistence.hibernate.pagination.Log4j2InMemoryPaginationAppender.

No hay que elegir entre ellos: el starter detecta el sistema de registro activo y registra el appender adecuado.

Establezca axelix.sbs.transaction.monitoring.in-memory-pagination-detection.enabled en false si desea impedir que se registre cualquiera de los appenders.

axelix:
  sbs:
    transaction:
      monitoring:
        in-memory-pagination-detection:
          enabled: false

En esta página

Editar en GitHubInformar de un problema