Migration

Migrating from 3.x to 4.0

Version 4.0 is an intentional platform upgrade and not a drop-in dependency update:

  1. Upgrade the application runtime to Java 17 or newer.
  2. Upgrade Logback Classic/Core to 1.6.3 and SLF4J to 2.0.18.
  3. If access logging is used, replace ch.qos.logback:logback-access with ch.qos.logback.access:logback-access-common:2.0.15. Custom Java code that directly uses Logback Access types must move from ch.qos.logback.access.* to ch.qos.logback.access.common.* packages.
  4. If the application integrates with the appender's Jackson types, migrate imports from com.fasterxml.jackson.* to Jackson 3's tools.jackson.* packages. Normal XML appender configuration is unaffected.
  5. If structured arguments are used, upgrade net.logstash.logback:logstash-logback-encoder to 9.0.
  6. 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:

  1. Replace the dependency coordinates with com.agido:logback-elasticsearch-appender:4.0.0.
  2. Change appender class names from com.internetitem.logback.elasticsearch.* to com.agido.logback.elasticsearch.*.
  3. In XML configuration, prefer <esProperty> inside <properties>. The original <property> element remains supported; <esProperty> was added for Logback 1.3 compatibility.
  4. Review authentication and shutdown configuration described below.
  5. 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.ElasticsearchAppender
  • com.internetitem.logback.elasticsearch.ElasticsearchAccessAppender
  • com.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.