Dropwizard GELF

October 19, 2018 · View on GitHub

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

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.3.0-1</version>
</dependency>

Dropwizard GELF

Usage

Logging startup errors to Graylog

Configuration

Configuration settings

Host specification

Additional field types

Maven Artifacts

Support

Acknowledgements

Contributors

License