logstash-logback-encoder-5.0

Overview

Version 5.0 is a major release with several new features and bugfixes.

Several backwards incompatibilities were introduced (see section below). Most have the ability to revert to previous behavior via config changes if necessary.

Support for Java 1.6 has been removed. Java 1.7 or above is now required.

New Features

• Added Appender Listeners so that applications can receive notifications for the appender lifecycle and event processing. In the future, listeners can be added to implement metrics (#126 ) or customized error handling/reporting (#159, #127). Applications can also provide their own listeners.
• #194 Added Header Filters for deciding which request/response headers to include in access events
• #251 Added a #tryJson pattern operation to fall back to just printing the message if the argument is not valid JSON
• #258 Added a timestampPattern configuration property to LogstashEncoder, LogstashLayout, LogstashAccessEncoder, and LogstashAccessLayout
• Added CompositeJsonFactoryDecorator and CompositeJsonGeneratorDecorator to make it easier to add multiple decorators.
• #257 @jackhammer2k Added new throwableClassName and throwableRootCauseClassName JSON providers

Bug fixes / Minor improvements

• #241 Fixed the pattern JsonProvider to be able to be used within the nestedField JsonProvider
• #237 Fixed setting the buffer initial capacity of the ShortenedThrowableConverter
• #243 Documented using dependencyManagment to sync logback dependency versions
• #259 Upgraded jackson dependencies to 2.9.4 as mentioned in dependency version changes below (@haus contributed to this update)
• com.fasterxml.uuid:java-uuid-generator is no longer included in the logstash-logback-encoder jar, and is now an optional dependency
• #240 @robsonbittencourt Fixed anchors in README.md

Dependency version changes

Usage	Dependency	Old Version	New Version
Runtime	jackson	2.8.9	2.9.4
Runtime (shaded)	disruptor	3.3.4	3.3.8
Compile-time	animal-sniffer	1.15	1.16
Test-time	assertj	2.4.0	2.9.0
Test-time	mockito	1.10.19	2.9.0
Test-time	powermock	1.6.5	1.7.3
Test-time	commons-io	2.4	2.6

Backwards Incompatibilities

• Support for Java 1.6 has been removed. Java 1.7 or above is now required.

• For #112, the default maxDepthPerThrowable of the ShortenedThrowableConverter has been changed to be full/unlimited to be be better aligned with its other configuration parameters.

  To revert to the old value, specify 25 for the maxDepthPerThrowable as documented here

• For #138 and #150, access event field names have been changed.

  Old field name	New field name
  @fields.content_length	content_length
  @fields.elapsed_time	elapsed_time
  @fields.method	method
  @fields.protocol	protocol
  @fields.requested_url	requested_url
  @fields.requested_uri	requested_uri
  @fields.remote_host	remote_host
  @fields.remote_user	remote_user
  @fields.status_code	status_code
  @fields.HOSTNAME	n/a
  @message	message

  To revert to the old field names, specify the following in the encoder/layout configuration:

  <fieldNames class="net.logstash.logback.fieldnames.Pre50LogstashAccessFieldNames"/>

• For #176, the @fields.hostname field has been removed. It's value was always the same as the @fields.remoteHost field value (which is now the remoteHost field)

• For #169, the arguments JSON provider has been enabled by default in the LogstashEncoder, LogstashLayout, LogstashAccessEncoder, and LogstashAccessLayout

  To disable the arguments provider, specify the following in the encoder/layout configuration:

  <includeStructuredArguments>false</includeStructuredArguments>

• For #174, the default field type of the @version field has changed from an integer to a string.

  To change the @version field type back to an integer, specify the following in the encoder/layout configuration:

  <writeVersionAsInteger>true</writeVersionAsInteger>

  or, if you are using the version provider directly, specify the following in the version provider configuration:

  <writeAsInteger>true</writeAsInteger>

• For #261 ESCAPE_NON_ASCII is now disabled by default

  To reenable it, you can use the EscapeNonAsciiJsonFactoryDecorator by specifying the following in the encoder/layout configuration:

  <jsonFactoryDecorator class="net.logstash.logback.decorate.EscapeNonAsciiJsonFactoryDecorator"/>

  If you were already using a jsonFactoryDecorator, you can use the new CompositeJsonFactoryDecorator to add multiple JsonFactoryDecorators

• Request/response header names are now written in lowercase by default

  To revert to the original behavior, specify the following in the encoder/layout/provider configuration:

  <lowerCaseHeaderNames>false</lowerCaseHeaderNames>

logstash-logback-encoder-4.11

• #226 / #228 Add ability to calculate hashes of stack traces (via a StackHashJsonProvider and ShortenedThrowableConverter)
• #230 / #231 Update Jackson to 2.8.9.

logstash-logback-encoder-4.10

• #195 Add destination connection strategies (preferPrimary, roundRobin, random)
• #199 Update jackson dependency to 2.8.8.
  • Note that jackson-databind 2.8 requires Java 7+.
  • At this point logstash-logback-encoder should still work with jackson 2.6/2.7, so you can use dependency management to downversion to an older version of jackson if needed
• #211 Added new asJson operator for the pattern json provider
• #218 Allow disabling the output stream buffer
• #219 Add a new provider for generating a random UUID
• #217 Fix markdown in readme
• #216 Clarify that HOSTNAME field was removed from logback context in logback 1.1.10

logstash-logback-encoder-4.9

• #205 Make compatible with logback 1.2.x (while still maintaining runtime compatibility with logback 1.1.x)
• #192 Fix typo in README.md

logstash-logback-encoder-4.8

• #165 Fix documentation for ShortenedThrowableConverter
• #171 Add ability to output version field as string (instead of number)
• #172 / #173 Stop providers when JsonProviders.stop() is called (instead of starting them)
• #175 Remove out-of-date disclaimer on logback issue
• #186 Document how to end prefix/suffix with whitespace
• #187 Fix typo in documentation
• #190 disable SerializationFeature.FAIL_ON_EMPTY_BEANS by default, and add better error handling around failed serializations

logstash-logback-encoder-4.7

• #149 Don't log stacktrace for unknown host exception
• #139 Add support for global custom fields for access events
  • Note that net.logstash.logback.composite.loggingevent.GlobalCustomFieldsJsonProvider was moved to net.logstash.logback.composite.GlobalCustomFieldsJsonProvider
• #161 Fix NPE when set/get custom fields programmatically
• #163 Normalize access log Response/Request headers (to lowercase)
• Updated 3rd party libraries
  • logback 1.1.6 (from 1.1.3)
  • jackson 2.6.5 (from 2.5.4)
  • disruptor 3.3.4 (from 3.3.2)
  • assertj 2.4.0 (from 2.1.0) (test only)
  • animal-sniffer 1.15 (from 1.14) (buildtime only)
• Misc Documentation Improvements
  • #147 Add documentation example for JsonFactoryDecorator
  • #137 Fix ecnoder for AccessTcpSocketAppender example
  • #158 Fix prefix/suffix documentation
  • #133 Document reconnectionDelay
  • #135 Clarify xml element name to use for renaming fields

logstash-logback-encoder-4.6

• #131 Add json provider for nested objects, so that logstash format version 0 can be created using the composite encoder.
• #124, add JSON provider for adding logback context name to json output
• #134, check to ensure properties are defined when destinations are set using properties.

logstash-logback-encoder-4.5.1

• Fix #129 to remain runtime-compatible with java 1.6

logstash-logback-encoder-4.5

• #115 / #116 Failover TCP connections
  • Multiple destinations can now be specified for the TCP appenders. Logs are sent to the first that accepts a connection
  • Deprecated remoteHost / port config parameters in favor of destination config parameter
• #85 Reestablish TCP connection when socket's input stream reaches the end of the stream
  • Fixes reconnection issues when communicating with Amazon's Elastic Load Balancer (ELB)
• #114 Shutdown faster when keep alive is enabled (only works on java 1.7+)
• #119 Removed runtime dependency on commons-io
• #119 Reduced jar size by minimizing shaded jar
• #117 Detect incompatible apis at compile time using animal-sniffer-plugin

logstash-logback-encoder-4.4

Backwards Incompatibility:

As part of the introduction of StructuredArguments (#99), the return type of the methods in net.logstash.logback.marker.Markers changed to net.logstash.logback.marker.LogstashMarker instead of specific subclasses of LogstashMarker.

Before -> After

If your code stored the result of those methods in a variable of the old return type, then your code will encounter a compile-time error on upgrade. You will need to change the type of your variable to LogstashMarker.

For example, change this:

        ObjectAppendingMarker marker = Markers.append("foo", foo);

to this:

        LogstashMarker marker = Markers.append("foo", foo);

If your code used inline markers (perhaps also with method chaining) without assigning them to variables you will encounter runtime errors. You will need to recompile your code to fix the runtime errors.

This backwards incompatibility was inadvertently overlooked, otherwise we would have bumped the version to 5.0, since this project follows semantic versioning practices.

Changes:

• #99 Add StructuredArguments as an alternative to Markers for adding fields to the log event JSON output
• #110 Clear events from RingBuffer after they have been processed (fixes memory leak)
• #91 Introduced includeCallerData(to be consistent with logback), and deprecated includeCallerInfo
• #103 Fix isIncludeMdc()
• #102 fixed setting a prefix without a suffix on the CompositeJsonLayout
• #100 Created a provider for ILoggingEvent.getMessage()
• #104 Replace org.slf4j.helpers.LogstashBasicMarker with net.logstash.logback.marker.LogstashBasicMarker
• Updated dependency versions for logback, jackson, junit, assertj