Skip to content
Logback appender for sending GELF messages with zero additional dependencies
Branch: master
Clone or download
Latest commit d37bff7 May 19, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
config/checkstyle ignore year in copyright Jan 21, 2018
gradle/wrapper Updated gradle Feb 12, 2019
src reopen DatagramChannel if required, fixes #20 May 19, 2019
.gitignore ignore out directory Jul 14, 2018
.travis.yml Use oraclejdk8 to hopefully fix travis Dec 26, 2017
CHANGELOG.md release v2.0.1 May 19, 2019
LICENSE initial work Mar 7, 2016
README.md add important notes May 19, 2019
build.gradle release v2.0.1 May 19, 2019
gradlew Updated gradle Feb 12, 2019
gradlew.bat

README.md

Logback GELF

Build Status Maven Central

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

Latest release

The most recent release is 2.0.1, released May 19, 2019.

To add a dependency using Maven, use the following:

<dependency>
    <groupId>de.siegmar</groupId>
    <artifactId>logback-gelf</artifactId>
    <version>2.0.1</version>
</dependency>

To add a dependency using Gradle:

dependencies {
    compile 'de.siegmar:logback-gelf:2.0.1'
}

Features

  • UDP (with chunking)
  • TCP (with or without TLS encryption)
  • Deflate compression in UDP 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 7
  • Logback 1.2.3

Important notes

Version 2.0.0 of this library introduced a configuration change. If you were already using this library, update your configuration to keep it working!

Old format:

<layout class="de.siegmar.logbackgelf.GelfLayout">

New format:

<encoder class="de.siegmar.logbackgelf.GelfEncoder">

This change was introduced, as the API of the Encoder interface changed in Logback 1.2.0.

Example

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>

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

</configuration>

Simple TCP with TLS configuration:

<configuration>

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

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

</configuration>

Please note, that it is recommended to use Logback's AsyncAppender in conjunction with GelfTcpAppender or GelfTcpTlsAppender to send logs asynchronously. See the advanced configuration example below.

Advanced UDP configuration:

<configuration>

    <appender name="GELF" class="de.siegmar.logbackgelf.GelfUdpAppender">
        <graylogHost>localhost</graylogHost>
        <graylogPort>12201</graylogPort>
        <maxChunkSize>508</maxChunkSize>
        <useCompression>true</useCompression>
        <encoder class="de.siegmar.logbackgelf.GelfEncoder">
            <originHost>localhost</originHost>
            <includeRawMessage>false</includeRawMessage>
            <includeMarker>true</includeMarker>
            <includeMdcData>true</includeMdcData>
            <includeCallerData>false</includeCallerData>
            <includeRootCauseData>false</includeRootCauseData>
            <includeLevelName>false</includeLevelName>
            <shortPatternLayout class="ch.qos.logback.classic.PatternLayout">
                <pattern>%m%nopex</pattern>
            </shortPatternLayout>
            <fullPatternLayout class="ch.qos.logback.classic.PatternLayout">
                <pattern>%m%n</pattern>
            </fullPatternLayout>
            <staticField>app_name:backend</staticField>
            <staticField>os_arch:${os.arch}</staticField>
            <staticField>os_name:${os.name}</staticField>
            <staticField>os_version:${os.version}</staticField>
        </encoder>
    </appender>

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

</configuration>

Advanced TCP configuration:

<configuration>

    <appender name="GELF" class="de.siegmar.logbackgelf.GelfTcpAppender">
        <graylogHost>localhost</graylogHost>
        <graylogPort>12201</graylogPort>
        <connectTimeout>15000</connectTimeout>
        <reconnectInterval>300</reconnectInterval>
        <maxRetries>2</maxRetries>
        <retryDelay>3000</retryDelay>
        <poolSize>2</poolSize>
        <poolMaxWaitTime>5000</poolMaxWaitTime>
        <encoder class="de.siegmar.logbackgelf.GelfEncoder">
            <originHost>localhost</originHost>
            <includeRawMessage>false</includeRawMessage>
            <includeMarker>true</includeMarker>
            <includeMdcData>true</includeMdcData>
            <includeCallerData>false</includeCallerData>
            <includeRootCauseData>false</includeRootCauseData>
            <includeLevelName>false</includeLevelName>
            <shortPatternLayout class="ch.qos.logback.classic.PatternLayout">
                <pattern>%m%nopex</pattern>
            </shortPatternLayout>
            <fullPatternLayout class="ch.qos.logback.classic.PatternLayout">
                <pattern>%m%n</pattern>
            </fullPatternLayout>
            <staticField>app_name:backend</staticField>
            <staticField>os_arch:${os.arch}</staticField>
            <staticField>os_name:${os.name}</staticField>
            <staticField>os_version:${os.version}</staticField>
        </encoder>
    </appender>

    <appender name="ASYNC GELF" class="ch.qos.logback.classic.AsyncAppender">
        <appender-ref ref="GELF" />
    </appender>

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

</configuration>

Advanced TCP with TLS configuration:

<configuration>

    <appender name="GELF" class="de.siegmar.logbackgelf.GelfTcpTlsAppender">
        <graylogHost>localhost</graylogHost>
        <graylogPort>12201</graylogPort>
        <connectTimeout>15000</connectTimeout>
        <reconnectInterval>300</reconnectInterval>
        <maxRetries>2</maxRetries>
        <retryDelay>3000</retryDelay>
        <poolSize>2</poolSize>
        <poolMaxWaitTime>5000</poolMaxWaitTime>
        <trustAllCertificates>false</trustAllCertificates>
        <encoder class="de.siegmar.logbackgelf.GelfEncoder">
            <originHost>localhost</originHost>
            <includeRawMessage>false</includeRawMessage>
            <includeMarker>true</includeMarker>
            <includeMdcData>true</includeMdcData>
            <includeCallerData>false</includeCallerData>
            <includeRootCauseData>false</includeRootCauseData>
            <includeLevelName>false</includeLevelName>
            <shortPatternLayout class="ch.qos.logback.classic.PatternLayout">
                <pattern>%m%nopex</pattern>
            </shortPatternLayout>
            <fullPatternLayout class="ch.qos.logback.classic.PatternLayout">
                <pattern>%m%n</pattern>
            </fullPatternLayout>
            <staticField>app_name:backend</staticField>
            <staticField>os_arch:${os.arch}</staticField>
            <staticField>os_name:${os.name}</staticField>
            <staticField>os_version:${os.version}</staticField>
        </encoder>
    </appender>

    <appender name="ASYNC GELF" class="ch.qos.logback.classic.AsyncAppender">
        <appender-ref ref="GELF" />
    </appender>

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

</configuration>

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.
  • encoder: See Encoder configuration below.
  • 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.
  • useCompression: If true, compression of GELF messages is enabled. Default: true.

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.
  • encoder: See Encoder configuration below.
  • connectTimeout: Maximum time (in milliseconds) to wait for establishing a connection. A value of 0 disables the connect timeout. Default: 15,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.

de.siegmar.logbackgelf.GelfTcpTlsAppender

  • Everything from GelfTcpAppender
  • trustAllCertificates: If true, trust all TLS certificates (even self signed certificates). You should not use this in production! Default: false.

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.
  • includeMarker: If true, logback markers will be sent, too. Default: true.
  • 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.
  • appendNewline: If true, a system depended newline separator will be added at the end of each message. Don't use this in conjunction with TCP or UDP appenders, as this is only reasonable for console logging!
  • shortPatternLayout: Short message format. Default: "%m%nopex".
  • fullPatternLayout: Full message format (Stacktrace). Default: "%m%n".
  • staticFields: Additional, static fields to send to graylog. Defaults: none.

Contribution

  • Fork
  • Code
  • Add test(s)
  • Commit
  • Send me a pull request

Copyright

Copyright (C) 2016-2019 Oliver Siegmar

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA

You can’t perform that action at this time.