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 LogEvent
s. 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()
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.
For Maven add to your pom.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:
runtime 'io.opencensus:opencensus-contrib-log-correlation-log4j2:0.16.1'
OpenCensusTraceContextDataInjector
ContextDataInjector
overrideOverride Log4j's default ContextDataInjector
by setting the system property log4j2.contextDataInjector
to the full name of the class, io.opencensus.contrib.logcorrelation.log4j2.OpenCensusTraceContextDataInjector
.
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
opencensus-contrib-log-correlation-log4j2
adds the following key-value pairs to the LogEvent
context:
opencensusTraceId
- the lowercase base16 encoding of the current trace IDopencensusSpanId
- the lowercase base16 encoding of the current span IDopencensusTraceSampled
- 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 6 or above is required for using this artifact.