Upgrading
From 4.x to 5.0
Breaking changes
Health provider and watchdog (Spring Boot)
Showing the application health in the systemd status and reporting it to the watchdog are configured separately:
-
the Actuator health status is shown by default when Spring Boot Actuator is available; disable it with
systemd.status-providers.actuator-health.enabled=false; -
reporting the health to the watchdog is still opt-in (see Health providers);
-
HealthProvider beans of the application are used together with the built-in ones, instead of replacing the Actuator one;
-
the properties moved under
systemd.status-providers.actuator-health, and the old ones are ignored:4.x 5.0 systemd.health-provider.enabledsystemd.status-providers.actuator-health.healthsystemd.health-provider.unhealthy-status-codessystemd.status-providers.actuator-health.unhealthy-status-codessystemd.health-provider.unhealthy-pending-period-mssystemd.status-providers.actuator-health.unhealthy-delayunhealthy-delayis a duration such as60s; values without a unit are still in milliseconds.
Systemd status
-
Health: the status only names the unhealthy health contributors, such as
health status: unhealthy (db, redis), without their details, which any local user can read. The details are logged when the watchdog heartbeat is suppressed. -
Tomcat: the Tomcat status provider shows the connections and busy threads of each connector, such as
http-nio-8080: 8/8192 connections, 3/10 threads, and no longer needsserver.tomcat.mbeanregistry.enabled=true. -
New status providers, enabled by default, show more in the status. Disable the ones you do not need (see Status providers), such as:
systemd.status-providers.buffer-pools.enabled=false systemd.status-providers.task-executors.enabled=false
API changes
-
Systemd.builder()was removed: there is a single Systemd instance per process, returned by Systemd.instance(), whose periodic tasks takeDurations, and can be enabled, changed or disabled at any time:// 4.x Systemd systemd = Systemd.builder().statusUpdate(5, TimeUnit.SECONDS).extendTimeout(5, TimeUnit.SECONDS, TimeUnit.SECONDS.toMicros(29)) .watchdog(10, TimeUnit.SECONDS).build(); // 5.0 Systemd systemd = Systemd.instance(); systemd.enableStatusUpdate(Duration.ofSeconds(5)); systemd.enableExtendTimeout(Duration.ofSeconds(5), Duration.ofSeconds(29)); systemd.enableWatchdog(Duration.ofSeconds(10));To leave the watchdog disabled, leave out the call instead of passing a period of 0. Under Spring Boot, the instance is no longer a bean: use
Systemd.instance()instead of injecting it. -
The building blocks no longer take a
Systemdinstance: create SystemdLifecycle with the application context it is a bean of, ApplicationRunStatusProvider without arguments, and ApplicationContextStatusProvider with the bean factory alone. -
Status and health providers are added and removed, instead of set:
setStatusProviders(...)andsetHealthProvider(...)were replaced by addStatusProviders(…), removeStatusProviders(…), addHealthProviders(…) and removeHealthProviders(…), andgetHealthProvider()by getHealthProviders(). -
PendingHealthProviderwas removed: extend DelayableHealthProvider, implementing evaluateHealth(), and call setUnhealthyDelay(Duration.ofSeconds(60)) instead ofnew PendingHealthProvider(provider, 60, ChronoUnit.SECONDS). -
HealthProvider.Health is an immutable record: read it with healthy() and details(), and use Health.HEALTHY instead of
Health.healthy(). -
SystemdNotify can no longer be instantiated, and
SystemdServletContextListenerwas removed. -
The Spring Boot classes moved out of the
com.github.jpmsilva.jsystemdpackage: the building blocks, such as the status and health providers and ConditionalOnSystemd, tocom.github.jpmsilva.jsystemd.spring, and the autoconfiguration tocom.github.jpmsilva.jsystemd.spring.autoconfigure. Update the imports, and the exclusions of SystemdAutoConfiguration by name, if any. -
The status provider interface, the built-in status providers, and some of their beans, were renamed:
4.x 5.0 SystemdStatusProviderStatusProvider SystemdHeapStatusProviderHeapStatusProvider SystemdNonHeapStatusProviderNonHeapStatusProvider SystemdClassLoaderStatusProviderClassLoaderStatusProvider SystemdApplicationRunStatusProviderApplicationRunStatusProvider SystemdApplicationContextStatusProviderApplicationContextStatusProvider SystemdTomcatStatusProviderTomcatStatusProvider SystemdActuatorHealthProviderActuatorHealthStatusProvider SystemdHealthProviderPropertiesSystemdProperties, which has all the properties of the starter 4.x bean 5.0 bean systemdNotifyHeapStatussystemdHeapStatusProvidersystemdNotifyNonHeapStatussystemdNonHeapStatusProvidersystemdNotifyClassLoaderStatussystemdClassLoaderStatusProvidersystemdActuatorHealthProvidersystemdActuatorHealthStatusProvider -
The built-in status providers are no longer annotated with
@Order: the starter orders them 1000 apart (see Status providers), so check the@Orderof custom status providers placed between them. -
The constructor of ActuatorHealthStatusProvider takes a
HealthContributors, such as the registry, instead of aList<HealthIndicator>.
Other changes
- New Keycloak provider,
jsystemd-keycloak(see Keycloak). - The Spring Boot building blocks moved to a new module,
jsystemd-spring-boot: depend on it instead of the starter to use them without the autoconfiguration. - Status providers can be disabled and configured individually (see Status providers).
- Deadlocked threads can be detected, and reported to the watchdog (see Health providers).
- Under Java 25, the JNA dependency is no longer needed on 64-bit architectures, and can be excluded (see How to use).
- Systemd.close() tells systemd that the application is stopping, if not told before. Under Spring Boot, the instance is closed with the application context.
- New Systemd.isUnderSystemd() and Systemd.watchdogTimeout().
- Watchdog heartbeats are only sent between ready() and stopping(), when systemd enforces the watchdog.
- The timeout can also be extended while the application stops (see How to).
- Notify sockets in the abstract namespace (
@...) andvsock:addresses are supported. - A failing status or health provider no longer fails the application: it is left out of the status, or makes the application unhealthy.
- Under Spring Boot, only closing the application context tells systemd that the application is stopping: stopping or pausing it, as for a CRaC checkpoint, no longer does.
- The periodic tasks run on their own threads,
jsystemd-status,jsystemd-watchdogandjsystemd-extend-timeout, instead of a singlejsystemd-N. - The startup status no longer includes an application identifier.
- Under Spring Boot, systemd can be notified that the application is ready before its runners run, with
systemd.ready-event=application-started(see How to). - Under Spring Cloud, only the actual application talks to systemd (see Application hierarchies).
