OpenCensus Log4j 2 Log Correlation

This subproject is currently experimental, so it may be redesigned or removed in the future. It
will remain experimental until we have a specification for a log correlation feature in
opencensus-specs
(issue #123).

The opencensus-contrib-log-correlation-log4j2 artifact provides a
Log4j 2
ContextDataInjector
that automatically adds tracing data to the context of Log4j
LogEvents.
The class name is
OpenCensusTraceContextDataInjector. OpenCensusTraceContextDataInjector adds the current trace
ID, span ID, and sampling decision to each LogEvent, so that they can be accessed with
[LogEvent.getContextData()](https://logging.apache.org/log4j/2.x/log4j-core/apidocs/org/apache/logging/log4j/core/LogEvent.html#getContextData())
or included in a layout.

See
https://github.com/census-ecosystem/opencensus-experiments/tree/master/java/log_correlation/log4j2
for a demo that uses this library to correlate logs and traces in Stackdriver.

Instructions

Add the dependencies to your project

For Maven add to your pom.xml:
xml <dependencies> <dependency> <groupId>io.opencensus</groupId> <artifactId>opencensus-contrib-log-correlation-log4j2</artifactId> <version>0.16.1</version> <scope>runtime</scope> </dependency> </dependencies>

For Gradle add to your dependencies:
groovy runtime 'io.opencensus:opencensus-contrib-log-correlation-log4j2:0.16.1'

Configure the OpenCensusTraceContextDataInjector

Specify the ContextDataInjector override

Override Log4j's default ContextDataInjector by setting the system property
log4j2.contextDataInjector to the full name of the class,
io.opencensus.contrib.logcorrelation.log4j2.OpenCensusTraceContextDataInjector.

Choose when to add tracing data to log events

The following system property controls the decision to add tracing data from the current span to a
log event:

io.opencensus.contrib.logcorrelation.log4j2.OpenCensusTraceContextDataInjector.spanSelection

The allowed values are:

• ALL_SPANS: adds tracing data to all log events (default)

• NO_SPANS: disables the log correlation feature

• SAMPLED_SPANS: adds tracing data to log events when the current span is sampled

Add the tracing data to log entries

opencensus-contrib-log-correlation-log4j2 adds the following key-value pairs to the LogEvent
context:

• opencensusTraceId - the lowercase base16 encoding of the current trace ID
• opencensusSpanId - the lowercase base16 encoding of the current span ID
• opencensusTraceSampled - the sampling decision of the current span ("true" or "false")

These values can be accessed from layouts with
Context Map Lookup. For
example, the trace ID can be accessed with $${ctx:opencensusTraceId}. The values can also be
accessed with the X conversion character in
PatternLayout, for
example, %X{opencensusTraceId}.

See an example Log4j configuration file in the demo:
https://github.com/census-ecosystem/opencensus-experiments/tree/master/java/log_correlation/log4j2/src/main/resources/log4j2.xml

Java Versions

Java 6 or above is required for using this artifact.