/dropwizard-gelf

Addon bundle for Dropwizard to support logging to a GELF-enabled server like Graylog or logstash

Primary LanguageJavaApache License 2.0Apache-2.0

Dropwizard GELF

Build Status Coverage Status Maven Central

Addon for Dropwizard adding support for logging to a GELF-enabled server such as Graylog or logstash using logstash-gelf.

Usage

The Dropwizard GELF provides an AppenderFactory which is automatically registered in Dropwizard and will send log messages directly to your configured GELF-enabled server.

Logging startup errors to Graylog

In order to log startup errors (i. e. before the GelfAppenderFactory has been properly initialized) to a GELF-enabled server, the Dropwizard application has to run GelfBootstrap.bootstrap() in its main method and set a custom UncaughtExceptionHandler for the main thread.

public static void main(String[] args) throws Exception {
    GelfBootstrap.bootstrap(NAME, GELF_HOST, GELF_PORT, false);
    Thread.currentThread().setUncaughtExceptionHandler(
            UncaughtExceptionHandlers.loggingSystemExitBuilder(NAME, GELF_HOST)
                    .port(GELF_PORT)
                    .build());

    new MyDropwizardApplication().run(args);
}

Configuration

The Logback GELF appender can be configured using the provided GelfConfiguration class which basically mirrors the appender configuration outlined in the logstash-gelf documentation.

Your YAML configuration could include the following snippet to configure the GelfLoggingBundle:

appenders:
  - type: console
  - type: gelf
    host: udp:graylog.example.com
    # port: 12201
    # facility: MyApplication
    # threshold: ALL
    # originHost: my-shiny-host
    extractStackTrace: true
    filterStackTrace: true
    includeFullMDC: true
    includeLocation: true
    additionalFields:
      data_center: DC01
      rack: R5C2
      inception_year: 2016
    additionalFieldTypes:
      inception_year: long
      request_id: long

Configuration settings

Setting Default Description
enabled true Specify if logging to a GELF-compatible server should be enabled.
facility [application name] The name of the application. Appears in the facility column in the Graylog web interface.
host [empty] Hostname/IP-Address of the GELF-compatible server, see host specification.
port 12201 Port of the GELF-compatible server.
originHost [FQDN hostname] Originating hostname.
extractStackTrace false Send the stack-trace to the StackTrace field.
filterStackTrace false Perform stack-trace filtering, see Stack Trace Filter.
mdcProfiling false Perform Profiling (Call-Duration) based on MDC Data. See MDC Profiling for details.
additionalFields [empty] Map of additional static fields.
additionalFieldTypes [empty] Map of type specifications for additional and MDC fields. See Additional field types for details.
mdcFields [empty] List of additional fields whose values are obtained from MDC.
dynamicMdcFields [empty] Dynamic MDC Fields allows you to extract MDC values based on one or more regular expressions. The name of the MDC entry is used as GELF field name.
includeFullMdc false Include all fields from the MDC.
includeLocation true Include source code location.
maximumMessageSize 8192 Maximum message size (in bytes). If the message size is exceeded, the appender will submit the message in multiple chunks (UDP only).
timestampPattern yyyy-MM-dd HH:mm:ss,SSSS Date/time pattern for the time field.

Host specification

Additional field types

Supported types: String, long, Long, double, Double and discover (default if not specified).

Maven Artifacts

This project is available on Maven Central. To add it to your project simply add the following dependencies to your POM:

<dependency>
  <groupId>net.gini.dropwizard</groupId>
  <artifactId>dropwizard-gelf</artifactId>
  <version>1.3.0-1</version>
</dependency>

Support

Please file bug reports and feature requests in GitHub issues.

Acknowledgements

Thanks to Nick Telford for his initial version of the GraylogBundle.

Contributors

License

Copyright (c) 2012-2013 smarchive GmbH, 2013-2018 Gini GmbH, 2015-2018 Jochen Schalanda

This library is licensed under the Apache License, Version 2.0.

See http://www.apache.org/licenses/LICENSE-2.0.html or the LICENSE file in this repository for the full license text.