Configuration

The following example shows the available settings. Only url and index are required for Elasticsearch or OpenSearch delivery.

<appender name="ELASTIC"
          class="com.agido.logback.elasticsearch.ElasticsearchAppender">
    <url>http://yourserver/_bulk</url>
    <index>logs-%date{yyyy-MM-dd}</index>
    <type>tester</type>
    <loggerName>es-logger</loggerName>
    <errorLoggerName>es-error-logger</errorLoggerName>
    <connectTimeout>30000</connectTimeout>
    <readTimeout>30000</readTimeout>
    <shutdownTimeout>30000</shutdownTimeout>
    <sleepTime>250</sleepTime>
    <maxQueueSize>104857600</maxQueueSize>
    <maxRetries>3</maxRetries>
    <maxBatchSize>-1</maxBatchSize>
    <includeCallerData>false</includeCallerData>
    <errorsToStderr>false</errorsToStderr>
    <logsToStderr>false</logsToStderr>
    <rawJsonMessage>false</rawJsonMessage>
    <includeMdc>false</includeMdc>
    <includeKvp>false</includeKvp>
    <maxMessageSize>-1</maxMessageSize>
    <objectSerialization>false</objectSerialization>
    <keyPrefix>data.</keyPrefix>
    <operation>create</operation>
    <timestampFormat>yyyy-MM-dd'T'HH:mm:ss.SSSZ</timestampFormat>

    <properties>
        <esProperty>
            <name>host</name>
            <value>${HOSTNAME}</value>
            <allowEmpty>false</allowEmpty>
        </esProperty>
        <esProperty>
            <name>severity</name>
            <value>%level</value>
        </esProperty>
    </properties>

    <headers>
        <header>
            <name>Content-Type</name>
            <value>application/json</value>
        </header>
    </headers>
</appender>

Configuration reference

  • url (required): Elasticsearch or OpenSearch Bulk API endpoint.
  • index (required): Target index. Supports Logback PatternLayout conversion words, for example logs-%date{yyyy-MM-dd}.
  • type (optional): Adds _type to each bulk action. Leave this unset for current Elasticsearch and OpenSearch versions; configure it only for a legacy API and mapping that still require document types.
  • sleepTime (default 250 ms, minimum 100): Delay when the event queue is empty. The queue is drained before sleeping.
  • maxBatchSize (default -1): Maximum events per batch. A positive number limits the batch; -1 drains the entire queue.
  • maxRetries (default 3): Retry attempts for pending data. A later event resets the retry count.
  • connectTimeout (default 30000 ms): HTTP connection timeout.
  • readTimeout (default 30000 ms): HTTP request timeout.
  • shutdownTimeout (default 30000 ms): Maximum wait for the worker during Logback shutdown. 0 waits indefinitely.
  • maxQueueSize (default 104857600 characters): Approximate send-buffer limit. New log data is dropped while the limit is exceeded.
  • includeCallerData (default false): Capture caller data before asynchronous processing.
  • errorsToStderr (default false): Also write delivery errors to stderr. Errors otherwise use Logback's internal status system.
  • logsToStderr (default false): Write raw Bulk API payloads to stderr.
  • loggerName (optional): Send raw Bulk API payloads to this logger.
  • errorLoggerName (optional): Send internal errors to this logger.
  • rawJsonMessage (default false): Treat the log message as preformatted JSON.
  • includeMdc (default false): Add all MDC values to the JSON payload.
  • includeKvp (default false): Add key-value pairs created with SLF4J's fluent LoggingEventBuilder API.
  • maxMessageSize (default -1): For values greater than 0, truncate longer messages and append ...
  • authentication (optional): Authentication implementation; see Authentication.
  • objectSerialization (default false): Enable Jackson POJO-to-JSON serialization and automatic module discovery.
  • keyPrefix (optional): Prefix for objects extracted from a structured message.
  • operation (default create): Bulk operation: index, create, update, or delete.
  • timestampFormat (optional): Custom timestamp format. Use long for epoch milliseconds.

The @timestamp and message fields are always sent. Additional fields use <esProperty> entries:

  • name (required): JSON field name.
  • value (required): Value rendered through Logback PatternLayout, including conversion words and substitutions such as ${HOSTNAME}.
  • allowEmpty (default false): Include a field whose rendered value is null or empty.
  • type (default String): One of String, int, float, or boolean.