Log4j2 Bunyan Layout

Overview

This project provides a custom Log4j Layout that outputs structured logs in the Bunyan JSON format. Similar to Log4j log4j2-bunyan-layout aims to minimize object creation and thereby garbage collection. Additionally, log4j2-bunyan-layout uses the DSL-JSON library for fast JSON serialization.

Configuration

Add a dependency definition to your Maven pom.xml:

<project>
    ...
    <dependencies>
        <dependency>
            <groupId>org.apache.logging.log4j</groupId>
            <artifactId>log4j-core</artifactId>
            <version>2.16.0</version>
        </dependency>
        <dependency>
            <groupId>com.github.dekobon</groupId>
            <artifactId>log4j2-bunyan-layout</artifactId>
            <version>1.0.3</version>
        </dependency>
    </dependencies>
</project>

Edit your log4j2 configuration such that you have added it as a layout to your appender. For example, a minimal configuration would look like:

<?xml version="1.0" encoding="UTF-8"?>
<Configuration>
    <Appenders>
        <File name="MyFile" fileName="output.json">
            <BunyanJsonLayout appName="space-explorer"/>
        </File>
    </Appenders>
    <Loggers>
        <Root level="debug">
            <AppenderRef ref="MyFile"/>
        </Root>
    </Loggers>
</Configuration>

A more robust configuration may look like:

...
        <File name="MyFile" fileName="output.json">
            <BunyanJsonLayout appName="road-hopper" endOfLine="\n" maxMessageLength="1000" properties="false">
                <ThrowableFormat format="extended" ignorePackages="org.junit"/>
                <KeyValuePair key="additionalField" value="constant value"/>
                <KeyValuePair key="traceId" value="$${ctx:trace_id:-}"/>
            </BunyanJsonLayout>
        </File>
...

The layout has the following properties.

BunyanJsonLayout

• appName (required) - string to use as application name in bunyan log messages.
• endOfLine - string to append to the end of each JSON object (default: (Unix new line) \n). This property accepts Java style escaped values such as: \n, \r, \t, \0. If there are octals, unicode, or any sort of non-trivial escapes in this value, Java 15+ must be used or the Apache Commons Text library must be loaded.
• maxMessageLength - size in characters to truncate log messages to (default: 32768).
• properties - flag when set to true enables the output of all context properties (default: false).

ThrowableFormat (Optional element - only a single element is valid)

• format - pattern in which to format exception (throwable) stack traces that are associated with a log event. If format is specified depth may not be specified. Format can be set to any of the following values:
  • none - no stacktrace is output.
  • full - the full stacktrace is output (default).
  • extended - outputs the full stacktrace including the location of where the class was loaded from and the version of the jar if available.
  • short - outputs the first line of the Throwable.
  • short.className - outputs the name of the class where the exception occurred.
  • short.methodName - outputs the method name where the exception occurred.
  • short.lineNumber - outputs the line number where the exception occurred.
  • short.fileName - outputs the name of the file where the exception occurred.
  • short.message - outputs only the message.
  • short.localizedMessage - outputs the localized message.
• depth - number of lines of the stack trace to output. If depth is specified format may not be specified.
• ignorePackages - a comma delimited list of Java packages to suppress matching stack frames from stack traces.

KeyValuePair (Optional element - many elements may be defined)

• key - String indicating the name of the value to be output as an additional log attribute.
• value - A string constant to output as an additional log attribute, or alternatively a dynamic value defined using Log4j2's lookup syntax.

License

This project is licensed under the Apache License v2 license.