Logback GELF

Logback appender for sending GELF (Graylog Extended Log Format) messages with zero additional dependencies.

Features

• UDP (with chunking)
• TCP (with or without TLS encryption)
• HTTP(s)
• GZIP and ZLIB compression (in UDP and HTTP mode)
• Client side load balancing (round-robin)
• Forwarding of MDC (Mapped Diagnostic Context)
• Forwarding of caller data
• Forwarding of static fields
• Forwarding of exception root cause
• No runtime dependencies beside Logback

Requirements

• Java 11
• Logback 1.5.3

Examples

Simple UDP configuration:

<configuration>

    <appender name="GELF" class="de.siegmar.logbackgelf.GelfUdpAppender">
        <graylogHost>localhost</graylogHost>
        <graylogPort>12201</graylogPort>
    </appender>

    <root level="debug">
        <appender-ref ref="GELF" />
    </root>

</configuration>

Simple TCP configuration:

<configuration>

    <appender name="GELF" class="de.siegmar.logbackgelf.GelfTcpAppender">
        <graylogHost>localhost</graylogHost>
        <graylogPort>12201</graylogPort>
    </appender>

    <!-- Use AsyncAppender to prevent slowdowns -->
    <appender name="ASYNC GELF" class="ch.qos.logback.classic.AsyncAppender">
        <appender-ref ref="GELF" />
        <neverBlock>true</neverBlock>
    </appender>

    <root level="debug">
        <appender-ref ref="ASYNC GELF" />
    </root>

</configuration>

Simple TCP with TLS configuration:

<configuration>

    <appender name="GELF" class="de.siegmar.logbackgelf.GelfTcpTlsAppender">
        <graylogHost>localhost</graylogHost>
        <graylogPort>12201</graylogPort>
    </appender>

    <!-- Use AsyncAppender to prevent slowdowns -->
    <appender name="ASYNC GELF" class="ch.qos.logback.classic.AsyncAppender">
        <appender-ref ref="GELF" />
        <neverBlock>true</neverBlock>
    </appender>

    <root level="debug">
        <appender-ref ref="ASYNC GELF" />
    </root>

</configuration>

Simple HTTP configuration:

<configuration>

    <appender name="GELF" class="de.siegmar.logbackgelf.GelfHttpAppender">
        <uri>https://my.server:12201/gelf</uri>
    </appender>

    <!-- Use AsyncAppender to prevent slowdowns -->
    <appender name="ASYNC GELF" class="ch.qos.logback.classic.AsyncAppender">
        <appender-ref ref="GELF" />
        <neverBlock>true</neverBlock>
    </appender>

    <root level="debug">
        <appender-ref ref="ASYNC GELF" />
    </root>

</configuration>

Find more advanced examples in the examples directory.

Configuration

Appender

de.siegmar.logbackgelf.GelfUdpAppender

• graylogHost: IP or hostname of graylog server. If the hostname resolves to multiple ip addresses, round-robin will be used.
• graylogPort: Port of graylog server. Default: 12201.
• maxChunkSize: Maximum size of GELF chunks in bytes. Default chunk size is 508 - this prevents IP packet fragmentation. This is also the recommended minimum. Maximum supported chunk size is 65,467 bytes.
• compressionMethod: Compression method to use (NONE, GZIP or ZLIB). Default: GZIP.
• messageIdSupplier: The mechanism that supplies unique message ids that are required by the GELF UDP protocol. Default: de.siegmar.logbackgelf.MessageIdSupplier.
• encoder: See Encoder configuration below.

de.siegmar.logbackgelf.GelfTcpAppender

• graylogHost: IP or hostname of graylog server. If the hostname resolves to multiple ip addresses, round-robin will be used.
• graylogPort: Port of graylog server. Default: 12201.
• connectTimeout: Maximum time (in milliseconds) to wait for establishing a connection. A value of 0 disables the connect timeout. Default: 15,000 milliseconds.
• socketTimeout: Maximum time (in milliseconds) to block when reading a socket. A value of 0 disables the socket timeout. Default: 5,000 milliseconds.
• reconnectInterval: Time interval (in seconds) after an existing connection is closed and re-opened. A value of -1 disables automatic reconnects. Default: 60 seconds.
• maxRetries: Number of retries. A value of 0 disables retry attempts. Default: 2.
• retryDelay: Time (in milliseconds) between retry attempts. Ignored if maxRetries is 0. Default: 3,000 milliseconds.
• poolSize: Number of concurrent tcp connections (minimum 1). Default: 2.
• poolMaxWaitTime: Maximum amount of time (in milliseconds) to wait for a connection to become available from the pool. A value of -1 disables the timeout. Default: 5,000 milliseconds.
• poolMaxIdleTime: Maximum amount of time (in seconds) that a pooled connection can be idle before it is considered 'stale' and will not be reused. A value of -1 disables the max idle time feature. Default: -1 (disabled).
• encoder: See Encoder configuration below.

de.siegmar.logbackgelf.GelfTcpTlsAppender

• Everything from GelfTcpAppender
• insecure: If true, skip the TLS certificate validation. You should not use this in production! Default: false.

de.siegmar.logbackgelf.GelfHttpAppender

• uri: HTTP(s) URI of graylog server (e.g. https://my.server:12201/gelf).
• insecure: If true, skip the TLS certificate validation. You should not use this in production! Default: false.
• connectTimeout: Maximum time (in milliseconds) to wait for establishing a connection. A value of 0 disables the connect timeout. Default: 15,000 milliseconds.
• requestTimeout: Maximum time (in milliseconds) to wait for a response. A value of 0 disables the timeout. Default: 5,000 milliseconds.
• maxRetries: Number of retries. A value of 0 disables retry attempts. Default: 2.
• retryDelay: Time (in milliseconds) between retry attempts. Ignored if maxRetries is 0. Default: 3,000 milliseconds.
• compressionMethod: Compression method to use (NONE, GZIP or ZLIB). Default: GZIP.
• encoder: See Encoder configuration below.

Encoder

de.siegmar.logbackgelf.GelfEncoder

• originHost: Origin hostname - will be auto-detected if not specified.
• includeRawMessage: If true, the raw message (with argument placeholders) will be sent, too. Default: false.
• includeKeyValues: If true, key value pairs will be sent, too. Default: true.
• includeMarker: If true, logback markers will be sent, too. Default: false.
• includeMdcData: If true, MDC keys/values will be sent, too. Default: true.
• includeCallerData: If true, caller data (source file-, method-, class name and line) will be sent, too. Default: false.
• includeRootCauseData: If true, root cause exception of the exception passed with the log message will be exposed in the root_cause_class_name and root_cause_message fields. Default: false.
• includeLevelName: If true, the log level name (e.g. DEBUG) will be sent, too. Default: false.
• levelNameKey: The key (i.e. the field name) that should be used for the log level name. This is only relevant when includeLevelName is true. Default: level_name.
• loggerNameKey: The key (i.e. the field name) that should be used for the logger name. Default: logger_name.
• threadNameKey: The key (i.e. the field name) that should be used for the thread name. Default: thread_name.
• appendNewline: If true, a system-dependent newline separator will be added at the end of each message. Don't use this in conjunction with TCP/UDP/HTTP appender, as this is only reasonable for console logging!
• shortMessageLayout: Short message format. Default: "%m%nopex".
• fullMessageLayout: Full message format (Stacktrace). Default: "%m%n".
• numbersAsString: Log numbers as String. Default: false.
• staticFields: Additional, static fields to send to graylog. Defaults: none.

Troubleshooting

If you have any problems, enable the debug mode and check the logs.

<configuration debug="true">
    ...
</configuration>