Dropwizard GELF

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
    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.
`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

udp:hostname for UDP transport, e. g. udp:127.0.0.1, udp:some.host.comor justsome.host.com`.
tcp:hostname for TCP transport, e. g. tcp:127.0.0.1 or tcp:some.host.com. See TCP transport for logstash-gelf for details.
ssl:hostname for TCP+SSL transport, e. g. ssl:127.0.0.1 or ssl:some.host.com. See TCP transport for logstash-gelf for details.
redis://[:password@]hostname:port/db-number#listname for Redis transport. See Redis transport for logstash-gelf for details.
redis-sentinel://[:password@]hostname:port/db-number?masterId=masterId#listname for Redis transport with Sentinel lookup. See Redis transport for logstash-gelf for details.
http://host[:port]/[path] for HTTP transport, e. g. https://127.0.0.1/gelf. See HTTP transport for logstash-gelf for details.

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.0.0-2</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

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.

alexwirz / dropwizard-gelf