Migration¶
Migrating from 3.x to 4.0¶
Version 4.0 is an intentional platform upgrade and not a drop-in dependency update:
- Upgrade the application runtime to Java 17 or newer.
- Upgrade Logback Classic/Core to 1.6.3 and SLF4J to 2.0.18.
- If access logging is used, replace
ch.qos.logback:logback-accesswithch.qos.logback.access:logback-access-common:2.0.15. Custom Java code that directly uses Logback Access types must move fromch.qos.logback.access.*toch.qos.logback.access.common.*packages. - If the application integrates with the appender's Jackson types, migrate
imports from
com.fasterxml.jackson.*to Jackson 3'stools.jackson.*packages. Normal XML appender configuration is unaffected. - If structured arguments are used, upgrade
net.logstash.logback:logstash-logback-encoderto 9.0. - Run the application's logging and search-engine integration tests before deploying.
Migrating from the original internetitem project¶
This project is a maintained fork, but it is not documented as a drop-in replacement. Migrate explicitly:
- Replace the dependency coordinates with
com.agido:logback-elasticsearch-appender:4.0.0. - Change appender class names from
com.internetitem.logback.elasticsearch.*tocom.agido.logback.elasticsearch.*. - In XML configuration, prefer
<esProperty>inside<properties>. The original<property>element remains supported;<esProperty>was added for Logback 1.3 compatibility. - Review authentication and shutdown configuration described below.
- Test delivery, retries, queue limits, and index mappings in a non-production environment.
Deprecated compatibility classes remain for these original appender names:
com.internetitem.logback.elasticsearch.ElasticsearchAppendercom.internetitem.logback.elasticsearch.ElasticsearchAccessAppendercom.internetitem.logback.elasticsearch.StructuredArgsElasticsearchAppender
They extend their com.agido equivalents, but are marked for removal. New and
migrated configurations should use the com.agido package.
Important change in 3.1.0: shutdown lifecycle¶
Version 3.1.0 removes the appender-specific JVM shutdown hook. Shutdown now uses
the standard Logback lifecycle, and the appender waits up to shutdownTimeout
(30 seconds by default) for queued events.
Spring Boot normally stops Logback automatically. Keep its logging shutdown hook enabled:
logging:
register-shutdown-hook: true
For applications without Spring Boot, configure Logback's shutdown hook:
<configuration>
<shutdownHook class="ch.qos.logback.core.hook.DefaultShutdownHook"/>
<!-- Appenders and loggers -->
</configuration>
Or stop the context programmatically:
LoggerContext context = (LoggerContext) LoggerFactory.getILoggerFactory();
Runtime.getRuntime().addShutdownHook(
new Thread(context::stop, "logback-shutdown")
);
Do not register both approaches. Set <shutdownTimeout>0</shutdownTimeout> to
wait indefinitely.