rk35xx-android12/external/opencensus-java/contrib/log_correlation/log4j2

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() 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:

<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'

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.