1 # OpenCensus Log4j 2 Log Correlation 2 3 This subproject is currently experimental, so it may be redesigned or removed in the future. It 4 will remain experimental until we have a specification for a log correlation feature in 5 [opencensus-specs](https://github.com/census-instrumentation/opencensus-specs/) 6 (issue [#123](https://github.com/census-instrumentation/opencensus-specs/issues/123)). 7 8 The `opencensus-contrib-log-correlation-log4j2` artifact provides a 9 [Log4j 2](https://logging.apache.org/log4j/2.x/) 10 [`ContextDataInjector`](https://logging.apache.org/log4j/2.x/manual/extending.html#Custom_ContextDataInjector) 11 that automatically adds tracing data to the context of Log4j 12 [`LogEvent`](https://logging.apache.org/log4j/2.x/log4j-core/apidocs/org/apache/logging/log4j/core/LogEvent.html)s. 13 The class name is 14 `OpenCensusTraceContextDataInjector`. `OpenCensusTraceContextDataInjector` adds the current trace 15 ID, span ID, and sampling decision to each `LogEvent`, so that they can be accessed with 16 [`LogEvent.getContextData()`](https://logging.apache.org/log4j/2.x/log4j-core/apidocs/org/apache/logging/log4j/core/LogEvent.html#getContextData()) 17 or included in a layout. 18 19 See 20 https://github.com/census-ecosystem/opencensus-experiments/tree/master/java/log_correlation/log4j2 21 for a demo that uses this library to correlate logs and traces in Stackdriver. 22 23 ## Instructions 24 25 ### Add the dependencies to your project 26 27 For Maven add to your `pom.xml`: 28 ```xml 29 <dependencies> 30 <dependency> 31 <groupId>io.opencensus</groupId> 32 <artifactId>opencensus-contrib-log-correlation-log4j2</artifactId> 33 <version>0.16.1</version> 34 <scope>runtime</scope> 35 </dependency> 36 </dependencies> 37 ``` 38 39 For Gradle add to your dependencies: 40 ```groovy 41 runtime 'io.opencensus:opencensus-contrib-log-correlation-log4j2:0.16.1' 42 ``` 43 44 ### Configure the `OpenCensusTraceContextDataInjector` 45 46 #### Specify the `ContextDataInjector` override 47 48 Override Log4j's default `ContextDataInjector` by setting the system property 49 `log4j2.contextDataInjector` to the full name of the class, 50 `io.opencensus.contrib.logcorrelation.log4j2.OpenCensusTraceContextDataInjector`. 51 52 #### Choose when to add tracing data to log events 53 54 The following system property controls the decision to add tracing data from the current span to a 55 log event: 56 57 `io.opencensus.contrib.logcorrelation.log4j2.OpenCensusTraceContextDataInjector.spanSelection` 58 59 The allowed values are: 60 61 * `ALL_SPANS`: adds tracing data to all log events (default) 62 63 * `NO_SPANS`: disables the log correlation feature 64 65 * `SAMPLED_SPANS`: adds tracing data to log events when the current span is sampled 66 67 ### Add the tracing data to log entries 68 69 `opencensus-contrib-log-correlation-log4j2` adds the following key-value pairs to the `LogEvent` 70 context: 71 72 * `opencensusTraceId` - the lowercase base16 encoding of the current trace ID 73 * `opencensusSpanId` - the lowercase base16 encoding of the current span ID 74 * `opencensusTraceSampled` - the sampling decision of the current span ("true" or "false") 75 76 These values can be accessed from layouts with 77 [Context Map Lookup](http://logging.apache.org/log4j/2.x/manual/lookups.html#ContextMapLookup). For 78 example, the trace ID can be accessed with `$${ctx:opencensusTraceId}`. The values can also be 79 accessed with the `X` conversion character in 80 [`PatternLayout`](http://logging.apache.org/log4j/2.x/manual/layouts.html#PatternLayout), for 81 example, `%X{opencensusTraceId}`. 82 83 See an example Log4j configuration file in the demo: 84 https://github.com/census-ecosystem/opencensus-experiments/tree/master/java/log_correlation/log4j2/src/main/resources/log4j2.xml 85 86 ### Java Versions 87 88 Java 6 or above is required for using this artifact. 89
