!! This document applies to the next version under development.
Provides logback encoders, layouts, and appenders to log in JSON format.
Supports both regular LoggingEvents (logged through a Logger
) and AccessEvents (logged via logback-access).
Originally written to support output in logstash's JSON format, but has evolved into a highly-configurable, general-purpose, JSON logging mechanism. The structure of the JSON output, and the data it contains, is fully configurable.
- Including it in your project
- Usage
- LoggingEvent Fields
- AccessEvent Fields
- Customizing Standard Field Names
- Customizing Version
- Customizing TimeZone
- Customizing JSON Factory and Generator
- Customizing Logger Name Length
- Customizing Stack Traces
- Prefix/Suffix
- Composite Encoder/Layout
- Debugging
Maven style:
<dependency>
<groupId>net.logstash.logback</groupId>
<artifactId>logstash-logback-encoder</artifactId>
<version>5.0</version>
</dependency>
If you get ClassNotFoundException
/NoClassDefFoundError
/NoSuchMethodError
at runtime, then ensure the required dependencies (and appropriate versions) as specified in the pom file from the maven repository exist on the runtime classpath. Specifically, the following need to be available on the runtime classpath:
- jackson-databind / jackson-core / jackson-annotations
- logback-core
- logback-classic (required for logging LoggingEvents)
- logback-access (required for logging AccessEvents)
- slf4j-api
Older versions than the ones specified in the pom file might work, but the versions in the pom file are what testing has been performed against.
If you are using logstash-logback-encoder in a project (such as spring-boot) that also declares dependencies on any of the above libraries, you might need to tell maven explicitly which versions to use to avoid conflicts. You can do so using maven's dependencyManagement feature. For example, to ensure that maven doesn't pick different versions of logback-core, logback-classic, and logback-access, add this to your project's pom.xml
<properties>
<ch.qos.logback.version>1.2.3</ch.qos.logback.version>
</properties>
<dependencyManagement>
<dependencies>
<dependency>
<groupId>ch.qos.logback</groupId>
<artifactId>logback-core</artifactId>
<version>${ch.qos.logback.version}</version>
</dependency>
<dependency>
<groupId>ch.qos.logback</groupId>
<artifactId>logback-classic</artifactId>
<version>${ch.qos.logback.version}</version>
</dependency>
<dependency>
<groupId>ch.qos.logback</groupId>
<artifactId>logback-access</artifactId>
<version>${ch.qos.logback.version}</version>
</dependency>
</dependencies>
</dependencyManagement>
To log using JSON format, you must configure logback to use either:
- an appender provided by the logstash-logback-encoder library, OR
- an appender provided by logback (or another library) with an encoder or layout provided by the logstash-logback-encoder library
The appenders, encoders, and layouts provided by the logstash-logback-encoder library are as follows:
Format | Protocol | Function | LoggingEvent | AccessEvent |
---|---|---|---|---|
Logstash JSON | Syslog/UDP | Appender | LogstashSocketAppender |
n/a |
Logstash JSON | TCP | Appender | LogstashTcpSocketAppender |
LogstashAccessTcpSocketAppender |
any | any | Appender | LoggingEventAsyncDisruptorAppender |
AccessEventAsyncDisruptorAppender |
Logstash JSON | any | Encoder | LogstashEncoder |
LogstashAccessEncoder |
Logstash JSON | any | Layout | LogstashLayout |
LogstashAccessLayout |
General JSON | any | Encoder | LoggingEventCompositeJsonEncoder |
AccessEventCompositeJsonEncoder |
General JSON | any | Layout | LoggingEventCompositeJsonLayout |
AccessEventCompositeJsonLayout |
These encoders/layouts can generally be used by any logback appender (such as RollingFileAppender
).
The general composite JSON encoders/layouts can be used to output any JSON format/data by configuring them with various JSON providers. The Logstash encoders/layouts are really just extensions of the general composite JSON encoders/layouts with a pre-defined set of providers.
The logstash encoders/layouts are easier to configure if you want to use the standard logstash version 1 output format. Use the composite encoders/layouts if you want to heavily customize the output, or if you need to use logstash version 0 output.
The *AsyncDisruptorAppender
appenders are similar to logback's AsyncAppender
,
except that a LMAX Disruptor RingBuffer
is used as the queuing mechanism, as opposed to a BlockingQueue
.
These async appenders can delegate to any other underlying logback appender.
To output JSON for LoggingEvents to a syslog/UDP channel,
use the LogstashSocketAppender
in your logback.xml
like this:
<?xml version="1.0" encoding="UTF-8"?>
<configuration>
<appender name="stash" class="net.logstash.logback.appender.LogstashSocketAppender">
<host>MyAwesomeSyslogServer</host>
<!-- port is optional (default value shown) -->
<port>514</port>
</appender>
<root level="all">
<appender-ref ref="stash" />
</root>
</configuration>
Internally, the LogstashSocketAppender
uses a LogstashLayout
to perform the JSON formatting.
Therefore, by default, the output will be logstash-compatible.
You can further customize the JSON output of LogstashSocketAppender
just like you can with a LogstashLayout
or LogstashEncoder
as described in later sections.
It is not necessary to configure a <layout>
or <encoder>
sub-element
within the <appender>
element in the logback configuration.
All the properties of LogstashLayout
or LogstashEncoder
can be set at the <appender>
level.
For example, to configure global custom fields, you can specify
<appender name="stash" class="net.logstash.logback.appender.LogstashSocketAppender">
<host>MyAwesomeSyslogServer</host>
<!-- port is optional (default value shown) -->
<port>514</port>
<customFields>{"appname":"myWebservice"}</customFields>
</appender>
There currently is no way to log AccessEvents over syslog/UDP.
To receive syslog/UDP input in logstash, configure a syslog
or udp
input with the json
codec in logstash's configuration like this:
input {
syslog {
codec => "json"
}
}
To output JSON for LoggingEvents over TCP, use a LogstashTcpSocketAppender
with a LogstashEncoder
or LoggingEventCompositeJsonEncoder
.
Example logging appender configuration in logback.xml
:
<?xml version="1.0" encoding="UTF-8"?>
<configuration>
<appender name="stash" class="net.logstash.logback.appender.LogstashTcpSocketAppender">
<destination>127.0.0.1:4560</destination>
<!-- encoder is required -->
<encoder class="net.logstash.logback.encoder.LogstashEncoder" />
</appender>
<root level="DEBUG">
<appender-ref ref="stash" />
</root>
</configuration>
To output JSON for AccessEvents over TCP, use a LogstashAccessTcpSocketAppender
with a LogstashAccessEncoder
or AccessEventCompositeJsonEncoder
.
Example access appender in logback-access.xml
<?xml version="1.0" encoding="UTF-8"?>
<configuration>
<appender name="stash" class="net.logstash.logback.appender.LogstashAccessTcpSocketAppender">
<destination>127.0.0.1:4560</destination>
<!-- encoder is required -->
<encoder class="net.logstash.logback.encoder.LogstashAccessEncoder" />
</appender>
<appender-ref ref="stash" />
</configuration>
Unlike the UDP appender, an encoder must be configured for the TCP appenders.
You can use a Logstash*Encoder
, *EventCompositeJsonEncoder
, or any other logback encoder.
All of the output formatting options are configured at the encoder level.
Internally, the TCP appenders are asynchronous (using the LMAX Disruptor RingBuffer).
All the encoding and TCP communication is delegated to a single writer thread.
There is no need to wrap the TCP appenders with another asynchronous appender
(such as AsyncAppender
or LoggingEventAsyncDisruptorAppender
).
All the configuration parameters (except for sub-appender) of the async appenders
are valid for TCP appenders. For example, waitStrategyType
and ringBufferSize
.
The TCP appenders will never block the logging thread. If the RingBuffer is full (e.g. due to slow network, etc), then events will be dropped.
The TCP appenders will automatically reconnect if the connection breaks. However, events may be lost before Java's socket realizes the connection has broken.
To receive TCP input in logstash, configure a tcp
input with the json_lines
codec in logstash's configuration like this:
input {
tcp {
port => 4560
codec => json_lines
}
}
In order to guarantee that logged messages have had a chance to be processed by the TCP appender, you'll need to cleanly shut down logback when your application exits.
If events occur infrequently, and the connection breaks consistently due to a server-side idle timeout,
then you can enable keep alive functionality by configuring a keepAliveDuration
like this:
<appender name="stash" class="net.logstash.logback.appender.LogstashTcpSocketAppender">
...
<keepAliveDuration>5 minutes</keepAliveDuration>
</appender>
When the keepAliveDuration
is set, then a keep alive message will be sent
if an event has not occurred for the length of the duration.
The keep alive message defaults to the system's line separator,
but can be changed by setting the keepAliveMessage
property.
The TCP appenders can be configured to try to connect to one of several destinations like this:
<appender name="stash" class="net.logstash.logback.appender.LogstashTcpSocketAppender">
<destination>destination1.domain.com:4560</destination>
<destination>destination2.domain.com:4560</destination>
<destination>destination3.domain.com:4560</destination>
...
</appender>
or this:
<appender name="stash" class="net.logstash.logback.appender.LogstashTcpSocketAppender">
<destination>
destination1.domain.com:4560,
destination2.domain.com:4560,
destination3.domain.com:4560
</destination>
...
</appender>
The appender uses a connectionStrategy
to determine:
- the order in which destination connections are attempted, and
- when an established connection should be reestablished (to the next destination selected by the connection strategy).
Logs are only sent to one destination at a time (i.e. not all destinations). By default, the appender will stay connected to the connected destination until it breaks, or until the application is shut down. Some connection strategies can force a reconnect (see below). If a connection breaks, then the appender will attempt to connect to the next destination selected by the connection strategy.
The available connection strategies are as follows:
Strategy | Description |
---|---|
preferPrimary | (default)
The first destination is considered the primary destination.
Each additional destination is considered a secondary destination.
This strategy prefers the primary destination, unless it is down.
The appender will attempt to connect to each destination in the order in which they are configured.
If a connection breaks, then the appender will again attempt to connect
to the destinations in the order in which they are configured,
starting at the first/primary destination.
The secondaryConnectionTTL can be set to gracefully close connections to secondary destinations after a specific duration. This will force the the appender to reattempt to connect to the destinations in order again. The secondaryConnectionTTL value does not affect connections to the primary destination. Example: <appender name="stash" class="net.logstash.logback.appender.LogstashTcpSocketAppender"> <destination>destination1.domain.com:4560</destination> <destination>destination2.domain.com:4560</destination> <destination>destination3.domain.com:4560</destination> <connectionStrategy> <preferPrimary> <secondaryConnectionTTL>5 minutes</secondaryConnectionTTL> </preferPrimary> </connectionStrategy> </appender> |
roundRobin |
This strategy attempts connections to the destination in round robin order.
If a connection fails, the next destination is attempted.
The connectionTTL can be set to gracefully close connections after a specific duration. This will force the the appender to reattempt to connect to the next destination. Example: <appender name="stash" class="net.logstash.logback.appender.LogstashTcpSocketAppender"> <destination>destination1.domain.com:4560</destination> <destination>destination2.domain.com:4560</destination> <destination>destination3.domain.com:4560</destination> <connectionStrategy> <roundRobin> <connectionTTL>5 minutes</connectionTTL> </roundRobin> </connectionStrategy> </appender> |
random |
This strategy attempts connections to the destination in a random order.
If a connection fails, the next random destination is attempted.
The connectionTTL can be set to gracefully close connections after a specific duration. This will force the the appender to reattempt to connect to the next random destination. Example: <appender name="stash" class="net.logstash.logback.appender.LogstashTcpSocketAppender"> <destination>destination1.domain.com:4560</destination> <destination>destination2.domain.com:4560</destination> <destination>destination3.domain.com:4560</destination> <connectionStrategy> <random> <connectionTTL>5 minutes</connectionTTL> </random> </connectionStrategy> </appender> |
You can also use your own custom connection strategy by implementing the DestinationConnectionStrategy
interface,
and configuring the appender to use it like this:
<appender name="stash" class="net.logstash.logback.appender.LogstashTcpSocketAppender">
<destination>destination1.domain.com:4560</destination>
<destination>destination2.domain.com:4560</destination>
<destination>destination3.domain.com:4560</destination>
<connectionStrategy class="your.package.YourDestinationConnectionStrategy">
</connectionStrategy>
</appender>
If connecting fails to all configured destinations, the TCP appender by default will wait 30 seconds before reattempting to connect.
This amount of time to delay can be changed by setting the reconnectionDelay
field.
<appender name="stash" class="net.logstash.logback.appender.LogstashTcpSocketAppender">
...
<reconnectionDelay>1 second</reconnectionDelay>
</appender>
By default, a buffer size of 8192 is used to buffer socket output stream writes.
You can adjust this by setting the appender's writeBufferSize
.
<appender name="stash" class="net.logstash.logback.appender.LogstashTcpSocketAppender">
...
<writeBufferSize>16384</writeBufferSize>
</appender>
Buffering can be disabled by setting the writeBufferSize
to 0
.
If buffering is disabled, the writer thread can slow down, but it will also can prevent dropping events in the buffer on flaky connections.
To use SSL, add an <ssl>
sub-element within the <appender>
element for the LogstashTcpSocketAppender
or LogstashAccessTcpSocketAppender
.
See the logback manual for how to configure SSL.
SSL for the Logstash*TcpSocketAppender
s are configured the same way as logback's SSLSocketAppender
.
For example, to enable SSL using the JVM's default keystore/truststore, do the following:
<appender name="stash" class="net.logstash.logback.appender.LogstashTcpSocketAppender">
...
<!-- Enable SSL using the JVM's default keystore/truststore -->
<ssl/>
</appender>
To use a different truststore, do the following:
<appender name="stash" class="net.logstash.logback.appender.LogstashAccessTcpSocketAppender">
...
<!-- Enable SSL and use a different truststore -->
<ssl>
<trustStore>
<location>classpath:server.truststore</location>
<password>${server.truststore.password}</password>
</trustStore>
</ssl>
</appender>
All the customizations that logback offers
(such as configuring cipher specs, protocols, algorithms, providers, etc.)
are supported by the Logback*TcpSocketAppender
s.
See the logstash documentation for the tcp
input
for how to configure it to use SSL.
The *AsyncDisruptorAppender
appenders are similar to logback's AsyncAppender
,
except that a LMAX Disruptor RingBuffer
is used as the queuing mechanism, as opposed to a BlockingQueue
.
These async appenders can delegate to any other underlying logback appender.
For example:
<appender name="async" class="net.logstash.logback.appender.LoggingEventAsyncDisruptorAppender">
<appender class="ch.qos.logback.core.rolling.RollingFileAppender">
...
</appender>
</appender>
The async appenders will never block the logging thread. If the RingBuffer is full (e.g. due to slow network, etc), then events will be dropped.
By default, the BlockingWaitStrategy
is used by the worker thread spawned by this appender.
The BlockingWaitStrategy
minimizes CPU utilization, but results in slower latency and throughput.
If you need faster latency and throughput (at the expense of higher CPU utilization), consider
a different wait strategy offered by the disruptor, such as SleepingWaitStrategy
.
The wait strategy can be configured on the async appender using the waitStrategyType
parameter, like this:
<appender name="async" class="net.logstash.logback.appender.LoggingEventAsyncDisruptorAppender">
<waitStrategyType>sleeping</waitStrategyType>
<appender class="ch.qos.logback.core.rolling.RollingFileAppender">
...
</appender>
</appender>
The supported wait strategies are as follows:
Wait Strategy | Parameters | Implementation |
---|---|---|
blocking | none | BlockingWaitStrategy |
busySpin | none | BusySpinWaitStrategy |
liteBlocking | none | LiteBlockingWaitStrategy |
sleeping | none | SleepingWaitStrategy |
yielding | none | YieldingWaitStrategy |
phasedBackoff{ spinTime, yieldTime, timeUnit, fallbackStrategy }e.g. phasedBackoff{10,60,seconds,blocking} |
|
PhasedBackoffWaitStrategy |
timeoutBlocking{ timeout, timeUnit }e.g. timeoutBlocking{1,minutes} |
|
TimeoutBlockingWaitStrategy |
See AsyncDisruptorAppender
for other configuration parameters (such as ringBufferSize
, producerType
, threadNamePrefix
, daemon
, and droppedWarnFrequency
)
In order to guarantees that logged messages have had a chance to be processed by asynchronous appenders (including the TCP appender) and ensure background threads have been stopped, you'll need to cleanly shut down logback when your application exits.
Listeners can be registered to an appender to receive notifications for the appender lifecycle and event processing.
See the two listener interfaces for the types of notifications that can be received:
AppenderListener
- basic notifications for the async appenders and udp appender.TcpAppenderListener
- extension ofAppenderListener
with additional TCP-specific notifications. Only works with the TCP appenders.
Some example use cases for a listener are:
- Monitoring metrics for events per second, event processing durations, dropped events, connections successes / failures, etc.
- Reporting event processing errors to a different appender (that perhaps appends to a different destination).
To create a listener, create a new class that extends one of the *ListenerImpl
classes or directly implements the *Listener
interface.
Extending the *ListenerImpl
class will have better backwards compatibilty in the future in case new methods are added to the interfaces.
(Logstash-logback-encoder still supports Java 7, so default interface methods cannot be used yet.)
Then register your listener class to an appender using the listener
xml element like this:
<appender name="stash" class="net.logstash.logback.appender.LogstashAccessTcpSocketAppender">
...
<listener class="your.package.YourListenerClass">
<yourListenerProperty>propertyValue</yourListenerProperty>
</listener>
</appender>
Multiple listeners can be registered by supplying multiple listener
xml elements.
You can use any of the encoders/layouts provided by the logstash-logback-encoder library with other logback appenders.
For example, to output LoggingEvents to a file, use the LogstashEncoder
with the RollingFileAppender
in your logback.xml
like this:
<?xml version="1.0" encoding="UTF-8"?>
<configuration>
<appender name="stash" class="ch.qos.logback.core.rolling.RollingFileAppender">
<filter class="ch.qos.logback.classic.filter.ThresholdFilter">
<level>info</level>
</filter>
<file>/some/path/to/your/file.log</file>
<rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
<fileNamePattern>/some/path/to/your/file.log.%d{yyyy-MM-dd}</fileNamePattern>
<maxHistory>30</maxHistory>
</rollingPolicy>
<encoder class="net.logstash.logback.encoder.LogstashEncoder" />
</appender>
<root level="all">
<appender-ref ref="stash" />
</root>
</configuration>
To log AccessEvents to a file, configure your logback-access.xml
like this:
<?xml version="1.0" encoding="UTF-8"?>
<configuration>
<appender name="stash" class="ch.qos.logback.core.rolling.RollingFileAppender">
<file>/some/path/to/your/file.log</file>
<encoder class="net.logstash.logback.encoder.LogstashAccessEncoder" />
</appender>
<appender-ref ref="stash" />
</configuration>
The LogstashLayout
and LogstashAccessLayout
can be configured the same way as
the LogstashEncoder
and LogstashAccessEncoder
. All the other examples
in this document use encoders, but the same options apply to the layouts as well.
To receive file input in logstash, configure a file
input in logstash's configuration like this:
input {
file {
path => "/some/path/to/your/file.log"
codec => "json"
}
}
The following sections describe the fields included in the JSON output by default for LoggingEvents written by the
LogstashEncoder
LogstashLayout
, and- the logstash appenders
If you are using the composite encoders/layouts, then the fields written will vary by the providers you configure.
These fields will appear in every LoggingEvent unless otherwise noted. The field names listed here are the default field names. The field names can be customized (see Customizing Standard Field Names).
Field | Description |
---|---|
@timestamp |
Time of the log event. (yyyy-MM-dd'T'HH:mm:ss.SSSZZ ) See customizing timezone. |
@version |
Logstash format version (e.g. 1 ) See customizing version. |
message |
Formatted log message of the event |
logger_name |
Name of the logger that logged the event |
thread_name |
Name of the thread that logged the event |
level |
String name of the level of the event |
level_value |
Integer value of the level of the event |
stack_trace |
(Only if a throwable was logged) The stacktrace of the throwable. Stackframes are separated by line endings. |
tags |
(Only if tags are found) The names of any markers not explicitly handled. (e.g. markers from MarkerFactory.getMarker will be included as tags, but the markers from Markers will not.) |
By default, each entry in the Mapped Diagnostic Context (MDC) (org.slf4j.MDC
)
will appear as a field in the LoggingEvent.
This can be fully disabled by specifying <includeMdc>false</includeMdc>
,
in the encoder/layout/appender configuration.
You can also configure specific entries in the MDC to be included or excluded as follows:
<encoder class="net.logstash.logback.encoder.LogstashEncoder">
<includeMdcKeyName>key1ToInclude</includeMdcKeyName>
<includeMdcKeyName>key2ToInclude</includeMdcKeyName>
</encoder>
or
<encoder class="net.logstash.logback.encoder.LogstashEncoder">
<excludeMdcKeyName>key1ToExclude</excludeMdcKeyName>
<excludeMdcKeyName>key2ToExclude</excludeMdcKeyName>
</encoder>
When key names are specified for inclusion, then all other fields will be excluded. When key names are specified for exclusion, then all other fields will be included. It is a configuration error to specify both included and excluded key names.
By default, each property of Logback's Context (ch.qos.logback.core.Context
)
will appear as a field in the LoggingEvent.
This can be disabled by specifying <includeContext>false</includeContext>
in the encoder/layout/appender configuration.
Note that logback versions prior to 1.1.10 included a HOSTNAME
property by default in the context.
As of logback 1.1.10, the HOSTNAME
property is lazily calculated (see LOGBACK-1221), and will no longer be included by default.
The encoder/layout/appender do not contain caller info by default. This can be costly to calculate and should be switched off for busy production environments.
To switch it on, add the includeCallerData
property to the configuration.
<encoder class="net.logstash.logback.encoder.LogstashEncoder">
<includeCallerData>true</includeCallerData>
</encoder>
If the encoder is included inside an asynchronous appender, such as
AsyncAppender
, LoggingEventAsyncDisruptorAppender
, or LogstashTcpSocketAppender
, then
includeCallerData
must be set to true on the appender as well.
When switched on, the following fields will be included in the log event:
Field | Description |
---|---|
caller_class_name |
Fully qualified class name of the class that logged the event |
caller_method_name |
Name of the method that logged the event |
caller_file_name |
Name of the file that logged the event |
caller_line_number |
Line number of the file where the event was logged |
In addition to the fields above, you can add other fields to the LoggingEvent either globally, or on an event-by-event basis.
Add custom fields that will appear in every LoggingEvent like this :
<encoder class="net.logstash.logback.encoder.LogstashEncoder">
<customFields>{"appname":"myWebservice","roles":["customerorder","auth"],"buildinfo":{"version":"Version 0.1.0-SNAPSHOT","lastcommit":"75473700d5befa953c45f630c6d9105413c16fe1"}}</customFields>
</encoder>
or in an AccessEvent like this :
<encoder class="net.logstash.logback.encoder.LogstashAccessEncoder">
<customFields>{"appname":"myWebservice","roles":["customerorder","auth"],"buildinfo":{"version":"Version 0.1.0-SNAPSHOT","lastcommit":"75473700d5befa953c45f630c6d9105413c16fe1"}}</customFields>
</encoder>
When logging a message, you can add additional fields to the JSON output by using
- structured arguments provided by
StructuredArguments
, OR - markers provided by
Markers
The difference between the two is that
StructuredArguments
are included in a the log event's formatted message (when the message has a parameter for the argument) AND in the JSON output.StructuredArguments
will be included in the JSON output if usingLogstashEncoder/Layout
or if using composite encoders/layouts with thearguments
provider.
Markers
are only written to the JSON output, and NEVER to the log event's formatted message.Markers
will be included in the JSON output if usingLogstashEncoder/Layout
or if using composite encoders/layouts with thelogstashMarkers
provider.
You can use StructuredArguments
even if the message does not contain a parameter
for the argument. However, in this case, the argument will only be written to the JSON output
and not the formatted message (which is effectively the same behavior that the Markers provide).
In general, you should use StructuredArguments
, unless you have a static analyzer
that flags parameter count / argument count mismatches.
Both StructuredArguments
and Markers
require constructing additional objects.
Therefore, it is best practice to surround the log lines with logger.isXXXEnabled()
,
to avoid the object construction if the log level is disabled.
Examples using StructuredArguments
:
import static net.logstash.logback.argument.StructuredArguments.*
/*
* Add "name":"value" to the JSON output,
* but only add the value to the formatted message.
*
* The formatted message will be `log message value`
*/
logger.info("log message {}", value("name", "value"));
/*
* Add "name":"value" to the JSON output,
* and add name=value to the formatted message.
*
* The formatted message will be `log message name=value`
*/
logger.info("log message {}", keyValue("name", "value"));
/*
* Add "name":"value" ONLY to the JSON output.
*
* Since there is no parameter for the argument,
* the formatted message will NOT contain the key/value.
*
* If this looks funny to you or to static analyzers,
* consider using Markers instead.
*/
logger.info("log message", keyValue("name", "value"));
/*
* Add multiple key value pairs to both JSON and formatted message
*/
logger.info("log message {} {}", keyValue("name1", "value1"), keyValue("name2", "value2")));
/*
* Add "name":"value" to the JSON output and
* add name=[value] to the formatted message using a custom format.
*/
logger.info("log message {}", keyValue("name", "value", "{0}=[{1}]"));
/*
* In the JSON output, values will be serialized by Jackson's ObjectMapper.
* In the formatted message, values will follow the same behavior as logback
* (formatting of an array or if not an array `toString()` is called).
*
* Add "foo":{...} to the JSON output and add `foo.toString()` to the formatted message:
*
* The formatted message will be `log message <result of foo.toString()>`
*/
Foo foo = new Foo();
logger.info("log message {}", value("foo", foo));
/*
* Add "name1":"value1","name2":"value2" to the JSON output by using a Map,
* and add `myMap.toString()` to the formatted message.
*
* Note the values can be any object that can be serialized by Jackson's ObjectMapper
* (e.g. other Maps, JsonNodes, numbers, arrays, etc)
*/
Map myMap = new HashMap();
myMap.put("name1", "value1");
myMap.put("name2", "value2");
logger.info("log message {}", entries(myMap));
/*
* Add "array":[1,2,3] to the JSON output,
* and array=[1,2,3] to the formatted message.
*/
logger.info("log message {}", array("array", 1, 2, 3));
/*
* Add fields of any object that can be unwrapped by Jackson's UnwrappableBeanSerializer to the JSON output.
* i.e. The fields of an object can be written directly into the JSON output.
* This is similar to the @JsonUnwrapped annotation.
*
* The formatted message will contain `myobject.toString()`
*/
logger.info("log message {}", fields(myobject));
/*
* In order to normalize a field object name, static helper methods can be created.
* For example, `foo(Foo)` calls `value("foo" , foo)`
*/
logger.info("log message {}", foo(foo));
Abbreviated convenience methods are available for all the structured argument types.
For example, instead of keyValue(key, value)
, you can use kv(key, value)
.
Examples using Markers
:
import static net.logstash.logback.marker.Markers.*
/*
* Add "name":"value" to the JSON output.
*/
logger.info(append("name", "value"), "log message");
/*
* Add "name1":"value1","name2":"value2" to the JSON output by using multiple markers.
*/
logger.info(append("name1", "value1").and(append("name2", "value2")), "log message");
/*
* Add "name1":"value1","name2":"value2" to the JSON output by using a map.
*
* Note the values can be any object that can be serialized by Jackson's ObjectMapper
* (e.g. other Maps, JsonNodes, numbers, arrays, etc)
*/
Map myMap = new HashMap();
myMap.put("name1", "value1");
myMap.put("name2", "value2");
logger.info(appendEntries(myMap), "log message");
/*
* Add "array":[1,2,3] to the JSON output
*/
logger.info(appendArray("array", 1, 2, 3), "log message");
/*
* Add "array":[1,2,3] to the JSON output by using raw json.
* This allows you to use your own json seralization routine to construct the json output
*/
logger.info(appendRaw("array", "[1,2,3]"), "log message");
/*
* Add any object that can be serialized by Jackson's ObjectMapper
* (e.g. Maps, JsonNodes, numbers, arrays, etc)
*/
logger.info(append("object", myobject), "log message");
/*
* Add fields of any object that can be unwrapped by Jackson's UnwrappableBeanSerializer.
* i.e. The fields of an object can be written directly into the json output.
* This is similar to the @JsonUnwrapped annotation.
*/
logger.info(appendFields(myobject), "log message");
See DEPRECATED.md for other deprecated ways of adding json to the output.
The following sections describe the fields included in the JSON output by default for AccessEvents written by the
LogstashAccessEncoder
,LogstashAccessLayout
, and- the logstash access appenders.
If you are using the composite encoders/layouts, then the fields written will vary by the providers you configure.
These fields will appear in every AccessEvent unless otherwise noted. The field names listed here are the default field names. The field names can be customized (see Customizing Standard Field Names).
Field | Description |
---|---|
@timestamp |
Time of the log event. (yyyy-MM-dd'T'HH:mm:ss.SSSZZ ) See customizing timezone. |
@version |
Logstash format version (e.g. 1 ) See customizing version. |
message |
Message in the form ${remoteHost} - ${remoteUser} [${timestamp}] "${requestUrl}" ${statusCode} ${contentLength} |
method |
HTTP method |
protocol |
HTTP protocol |
status_code |
HTTP status code |
requested_url |
Request URL |
requested_uri |
Request URI |
remote_host |
Remote host |
remote_user |
Remote user |
content_length |
Content length |
elapsed_time |
Elapsed time in millis |
Request and response headers are not logged by default, but can be enabled by specifying a field name for them, like this:
<encoder class="net.logstash.logback.encoder.LogstashAccessEncoder">
<fieldNames>
<requestHeaders>request_headers</requestHeaders>
<responseHeaders>response_headers</responseHeaders>
</fieldNames>
</encoder>
See Customizing Standard Field Names) for more details.
To write the header names in lowercase (so that header names that only differ by case are treated the same),
set lowerCaseFieldNames
to true, like this:
<encoder class="net.logstash.logback.encoder.LogstashAccessEncoder">
<fieldNames>
<requestHeaders>request_headers</requestHeaders>
<responseHeaders>response_headers</responseHeaders>
</fieldNames>
<lowerCaseHeaderNames>true</lowerCaseHeaderNames>
</encoder>
Headers can be filtered via configuring the requestHeaderFilter
and/or the responseHeaderFilter
with a HeaderFilter
, such as the
IncludeExcludeHeaderFilter
.
The IncludeExcludeHeaderFilter
can be configured like this:
<encoder class="net.logstash.logback.encoder.LogstashAccessEncoder">
<fieldNames>
<requestHeaders>request_headers</requestHeaders>
</fieldNames>
<requestHeaderFilter>
<include>Content-Type</include>
</requestHeaderFilter>
</encoder>
Custom filters implementing [`HeaderFilter`](/src/main/java/net/logstash/logback/composite/accessevent/HeaderFilter.java)
can be used by specifying the filter class like this:
```xml
<requestHeaderFilter class="your.package.YourFilterClass"/>
The standard field names above for LoggingEvents and AccessEvents can be customized by using the fieldNames
configuration element in the encoder or appender configuration.
For example:
<encoder class="net.logstash.logback.encoder.LogstashEncoder">
<fieldNames>
<timestamp>time</timestamp>
<message>msg</message>
...
</fieldNames>
</encoder>
Prevent a field from being output by setting the field name to [ignore]
.
For LoggingEvents, see LogstashFieldNames
for all the field names that can be customized. Each java field name in that class is the name of the xml element that you would use to specify the field name (e.g. logger
, levelValue
). Additionally, a separate set of shortened field names can be configured like this:
<encoder class="net.logstash.logback.encoder.LogstashEncoder">
<fieldNames class="net.logstash.logback.fieldnames.ShortenedFieldNames"/>
</encoder>
For LoggingEvents, log the caller info, MDC properties, and context properties
in sub-objects within the JSON event by specifying field
names for caller
, mdc
, and context
, respectively.
For AccessEvents, see LogstashAccessFieldNames
for all the field names that can be customized. Each java field name in that class is the name of the xml element that you would use to specify the field name (e.g. fieldsMethod
, fieldsProtocol
).
The version field value by default is the string value 1
.
The value can be changed like this:
<encoder class="net.logstash.logback.encoder.LogstashEncoder">
<version>2</version>
</encoder>
The value can be written as a number (instead of a string) like this:
<encoder class="net.logstash.logback.encoder.LogstashEncoder">
<writeVersionAsInteger>true</writeVersionAsInteger>
</encoder>
By default, timestamps are logged in the default TimeZone of the host Java platform. You can change the timezone like this:
<encoder class="net.logstash.logback.encoder.LogstashEncoder">
<timeZone>UTC</timeZone>
</encoder>
The value of the timeZone
element can be any string accepted by java's TimeZone.getTimeZone(String id)
method.
The JsonFactory
and JsonGenerator
used to serialize output can be customized by
instances of JsonFactoryDecorator
or JsonGeneratorDecorator
, respectively.
For example, you could enable pretty printing by using the PrettyPrintingJsonGeneratorDecorator
Or customize object mapping like this:
public class ISO8601DateDecorator implements JsonFactoryDecorator {
@Override
public MappingJsonFactory decorate(MappingJsonFactory factory) {
ObjectMapper codec = factory.getCodec();
codec.setDateFormat(new ISO8601DateFormat());
return factory;
}
}
and then specify the decorator in the logback.xml file like this:
<encoder class="net.logstash.logback.encoder.LogstashEncoder">
<jsonGeneratorDecorator class="net.logstash.logback.decorate.PrettyPrintingJsonGeneratorDecorator"/>
<jsonFactoryDecorator class="your.package.ISO8601DateDecorator"/>
</encoder>
See the net.logstash.logback.decorate package for other decorators.
For LoggingEvents, you can shorten the logger name field length similar to the normal pattern style of %logger{36}
.
Examples of how it is shortened can be found here
<encoder class="net.logstash.logback.encoder.LogstashEncoder">
<shortenedLoggerNameLength>36</shortenedLoggerNameLength>
</encoder>
For LoggingEvents, stack traces are formatted using logback's ExtendedThrowableProxyConverter
by default.
However, you can configure the encoder to use any ThrowableHandlingConverter
to format stacktraces.
A powerful ShortenedThrowableConverter
is included in the logstash-logback-encoder library to format stacktraces by:
- Limiting the number of stackTraceElements per throwable (applies to each individual throwable. e.g. caused-bys and suppressed)
- Limiting the total length in characters of the trace
- Abbreviating class names
- Filtering out consecutive unwanted stackTraceElements based on regular expressions.
- Using evaluators to determine if the stacktrace should be logged.
- Outputing in either 'normal' order (root-cause-last), or root-cause-first.
- Computing and inlining hexadecimal hashes for each exception stack (more info).
For example:
<encoder class="net.logstash.logback.encoder.LogstashEncoder">
<throwableConverter class="net.logstash.logback.stacktrace.ShortenedThrowableConverter">
<maxDepthPerThrowable>30</maxDepthPerThrowable>
<maxLength>2048</maxLength>
<shortenedClassNameLength>20</shortenedClassNameLength>
<exclude>sun\.reflect\..*\.invoke.*</exclude>
<exclude>net\.sf\.cglib\.proxy\.MethodProxy\.invoke</exclude>
<evaluator class="myorg.MyCustomEvaluator"/>
<rootCauseFirst>true</rootCauseFirst>
<inlineHash>true</inlineHash>
</throwableConverter>
</encoder>
ShortenedThrowableConverter
can even be used within a PatternLayout
to format stacktraces in any non-JSON logs you may have.
You can specify a prefix (written before the JSON object) and/or suffix (written after the JSON object), which may be required for the log pipeline you are using, such as:
- If you are using the Common Event Expression (CEE) format for syslog, you need to add the
@cee:
prefix. - If you are using other syslog destinations, you might need to add the standard syslog headers.
- If you are using Loggly, you might need to add your customer token.
For example, to add standard syslog headers for syslog over UDP, configure the following:
<configuration>
<conversionRule conversionWord="syslogStart" converterClass="ch.qos.logback.classic.pattern.SyslogStartConverter"/>
<appender name="stash" class="net.logstash.logback.appender.LogstashSocketAppender">
<host>MyAwesomeSyslogServer</host>
<!-- port is optional (default value shown) -->
<port>514</port>
<prefix class="ch.qos.logback.classic.PatternLayout">
<pattern>%syslogStart{USER}</pattern>
</prefix>
</appender>
...
</configuration>
When using the LogstashEncoder
, LogstashAccessEncoder
or a composite encoder, the prefix is an Encoder
, not a Layout
, so you will need to wrap the prefix PatternLayout
in a LayoutWrappingEncoder
like this:
<configuration>
...
<appender ...>
<encoder class="net.logstash.logback.encoder.LogstashEncoder">
...
<prefix class="ch.qos.logback.core.encoder.LayoutWrappingEncoder">
<layout class="ch.qos.logback.classic.PatternLayout">
<pattern>@cee:</pattern>
</layout>
</prefix>
</encoder>
</appender>
</configuration>
Note that logback's xml configuration reader will trim whitespace from xml element values. Therefore, if you want to end the prefix or suffix pattern with whitespace, first add the whitespace, and then add something like %mdc{keyThatDoesNotExist}
after it. For example <pattern>your pattern %mdc{keyThatDoesNotExist}</pattern>
. This will cause logback to output the whitespace as desired, and then a blank string for the MDC key that does not exist.
If you want greater flexibility in the JSON format and data included in LoggingEvents and AccessEvents, use the LoggingEventCompositeJsonEncoder
and AccessEventCompositeJsonEncoder
(or the corresponding layouts).
These encoders/layouts are composed of one or more JSON providers that contribute to the JSON output. No providers are configured by default in the composite encoders/layouts. You must add the ones you want.
For example:
<encoder class="net.logstash.logback.encoder.LoggingEventCompositeJsonEncoder">
<providers>
<mdc/>
<pattern>
<pattern>
{
"timestamp": "%date{ISO8601}",
"myCustomField": "fieldValue",
"relative": "#asLong{%relative}"
}
</pattern>
</pattern>
<stackTrace>
<throwableConverter class="net.logstash.logback.stacktrace.ShortenedThrowableConverter">
<maxDepthPerThrowable>30</maxDepthPerThrowable>
<maxLength>2048</maxLength>
<shortenedClassNameLength>20</shortenedClassNameLength>
<exclude>^sun\.reflect\..*\.invoke</exclude>
<exclude>^net\.sf\.cglib\.proxy\.MethodProxy\.invoke</exclude>
<evaluator class="myorg.MyCustomEvaluator"/>
<rootCauseFirst>true</rootCauseFirst>
</throwableConverter>
</stackTrace>
</providers>
</encoder>
The logstash-logback-encoder library contains many providers out-of-the-box,
and you can even plug-in your own by extending JsonProvider
.
Each provider has its own configuration options to further customize it.
For LoggingEvents, the available providers and their configuration properties (defaults in parenthesis) are as follows:
Provider | Description/Properties |
---|---|
timestamp | Event timestamp
|
version | Logstash JSON format version
|
message | Formatted log event message
|
rawMessage | Raw log event message, as opposed to formatted log where parameters are resolved
|
loggerName | Name of the logger that logged the message
|
threadName | Name of the thread from which the event was logged
|
logLevel | Logger level text (INFO, WARN, etc)
|
logLevelValue | Logger level numerical value
|
callerData | Outputs data about from where the logger was called (class/method/file/line)
|
stackTrace | Stacktrace of any throwable logged with the event. Stackframes are separated by newline chars.
|
stackHash | (Only if a throwable was logged) Computes and outputs a hexadecimal hash of the throwable stack. This helps identifying several occurrences of the same error (more info).
|
throwableClassName | (Only if a throwable was logged) Outputs a field that contains the class name of the thrown Throwable.
|
throwableRootCauseClassName | (Only if a throwable was logged) Outputs a field that contains the class name of the root cause of the thrown Throwable.
|
context | Outputs entries from logback's context
|
contextName | Outputs the name of logback's context
|
mdc |
Outputs entries from the Mapped Diagnostic Context (MDC). Will include all entries by default. When key names are specified for inclusion, then all other fields will be excluded. When key names are specified for exclusion, then all other fields will be included. It is a configuration error to specify both included and excluded key names.
|
tags | Outputs logback markers as a comma separated list
|
logstashMarkers | Used to output Logstash Markers as specified in Event-specific Custom Fields |
nestedField |
Nests a JSON object under the configured fieldName. The nested object is populated by other providers added to this provider.
|
pattern |
Outputs fields from a configured JSON Object string, while substituting patterns supported by logback's PatternLayout.
|
arguments |
Outputs fields from the event arguments array. See Event-specific Custom Fields
|
uuid | Outputs random UUID as field value. Handy when you want to provide unique identifier for log lines
|
For AccessEvents, the available providers and their configuration properties (defaults in parenthesis) are as follows:
Provider | Description/Properties |
---|---|
timestamp |
Event timestamp
|
version |
Logstash JSON format version
|
message |
Message in the form `${remoteHost} - ${remoteUser} [${timestamp}] "${requestUrl}" ${statusCode} ${contentLength}`
|
method |
HTTP method
|
protocol |
HTTP protocol
|
statusCode |
HTTP status code
|
requestedUrl |
Requested URL
|
requestedUri |
Requested URI
|
remoteHost |
Remote Host
|
remoteUser |
Remote User
|
contentLength |
Content length
|
elapsedTime |
Elapsed time in milliseconds
|
requestHeaders |
Include the request headers
|
responseHeaders |
Include the response headers
|
nestedField |
Nests a JSON object under the configured fieldName. The nested object is populated by other providers added to this provider.
|
pattern |
Outputs fields from a configured JSON Object string, while substituting patterns supported by logback access's PatternLayout.
|
Use the nestedField
provider to create a sub-object in the JSON event output.
For example...
<encoder class="net.logstash.logback.encoder.LoggingEventCompositeJsonEncoder">
<providers>
<timestamp/>
<nestedField>
<fieldName>fields</fieldName>
<providers>
<logLevel/>
</providers>
</nestedField>
</providers>
</encoder>
...will produce something like...
{
"@timestamp":"...",
"fields":{
"level": "DEBUG"
}
}
When used with a composite JSON encoder/layout, the pattern
JSON provider can be used to
define a template for a portion of the logged JSON output.
The encoder/layout will populate values within the template.
Every value in the template is treated as a pattern for logback's standard PatternLayout
so it can be a combination
of literal strings (for some constants) and various conversion specifiers (like %d
for date).
The pattern string (configured within the pattern provider) must be a JSON Object. The contents of the JSON object are included within the logged JSON output.
This example...
<encoder class="net.logstash.logback.encoder.LoggingEventCompositeJsonEncoder">
<providers>
<!-- provides the timestamp -->
<timestamp/>
<!-- provides the version -->
<version/>
<!-- provides the fields in the configured pattern -->
<pattern>
<!-- the pattern that defines what to include -->
<pattern>
{ "level": "%level" }
</pattern>
</pattern>
</providers>
</encoder>
... will produce something like...
{
"@timestamp":"...",
"@version": "1",
"level": "DEBUG"
}
The real power comes from the fact that there are lots of standard conversion specifiers so you
can customise what is logged and how. For example, you could log a single specific value from MDC with %mdc{mykey}
.
Or, for access logs, you could log a single request header with %i{User-Agent}
.
You can use nested objects and arrays in your pattern.
If you use a null, number, or a boolean constant in a pattern, it will keep its type in the
resulting JSON. However, only the text values are searched for conversion patterns.
And, as these patterns are sent through PatternLayout
, the result is always a string
even for something which you may feel should be a number - like for %b
(bytes sent, in access logs).
You can either deal with the type conversion on the logstash side or you may use special operations provided by this encoder. The operations are:
#asLong{...}
- evaluates the pattern in curly braces and then converts resulting string to a long (or a null if conversion fails).#asDouble{...}
- evaluates the pattern in curly braces and then converts resulting string to a double (or a null if conversion fails).#asJson{...}
- evaluates the pattern in curly braces and then converts resulting string to json (or a null if conversion fails).#tryJson{...}
- evaluates the pattern in curly braces and then converts resulting string to json (or just the string if conversion fails).
So this example...
<pattern>
{
"line_str": "%line",
"line_long": "#asLong{%line}",
"has_message": "#asJson{%mdc{hasMessage}}",
"json_message": "#asJson{%message}"
}
</pattern>
... And this logging code...
MDC.put("hasMessage", "true");
LOGGER.info("{\"type\":\"example\",\"msg\":\"example of json message with type\"}");
...will produce something like...
{
"line_str":"97",
"line_long":97,
"has_message":true,
"json_message":{"type":"example","msg":"example of json message with type"}
}
Note that the value that is sent for line_long
is a number even though in your pattern it is a quoted text.
And the json_message field value is a json object, not a string.
For LoggingEvents, patterns from logback-classic's
PatternLayout
are supported.
For example:
<encoder class="net.logstash.logback.encoder.LoggingEventCompositeJsonEncoder">
<providers>
<timestamp/>
<pattern>
<pattern>
{
"custom_constant": "123",
"tags": ["one", "two"],
"logger": "%logger",
"level": "%level",
"thread": "%thread",
"message": "%message",
...
}
</pattern>
</pattern>
</providers>
</encoder>
For AccessEvents, patterns from logback-access's
PatternLayout
are supported.
For example:
<encoder class="net.logstash.logback.encoder.AccessEventCompositeJsonEncoder">
<providers>
<pattern>
<pattern>
{
"custom_constant": "123",
"tags": ["one", "two"],
"remote_ip": "%a",
"status_code": "%s",
"elapsed_time": "%D",
"user_agent": "%i{User-Agent}",
"accept": "%i{Accept}",
"referer": "%i{Referer}",
"session": "%requestCookie{JSESSIONID}",
...
}
</pattern>
</pattern>
</providers>
</encoder>
There is also a special operation that can be used with this AccessEvents:
#nullNA{...}
- if the pattern in curly braces evaluates to a dash ("-"), it will be replaced with a null value.
You may want to use it because many of the PatternLayout
conversion specifiers from logback-access will evaluate to "-"
for non-existent value (for example for a cookie, header or a request attribute).
So the following pattern...
<pattern>
{
"default_cookie": "%requestCookie{MISSING}",
"filtered_cookie": "#nullNA{%requestCookie{MISSING}}"
}
</pattern>
...will produce...
{
"default_cookie": "-",
"filtered_cookie": null
}
During execution, the encoders/appenders/layouts provided in logstash-logback-encoder
will add logback status messages to the logback StatusManager
.
By default, logback only shows WARN/ERROR status messages on the console during configuration. No messages are output during actual operation (even if they are WARN/ERROR).
If you are having trouble identifying causes of problems (e.g. events are not getting delivered), then you can enable logback debugging or add a status listener as specified in the logback manual.
Memory usage and performance of logstash-logback-encoder have been improved by addressing issues discovered with the help of the YourKit Java Profiler.
YourKit, LLC has graciously donated a free license of the YourKit Java Profiler to this open source project.