diff options
Diffstat (limited to 'contrib/log_correlation/log4j2/README.md')
-rw-r--r-- | contrib/log_correlation/log4j2/README.md | 88 |
1 files changed, 0 insertions, 88 deletions
diff --git a/contrib/log_correlation/log4j2/README.md b/contrib/log_correlation/log4j2/README.md deleted file mode 100644 index a5bf1449..00000000 --- a/contrib/log_correlation/log4j2/README.md +++ /dev/null @@ -1,88 +0,0 @@ -# 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](https://github.com/census-instrumentation/opencensus-specs/) -(issue [#123](https://github.com/census-instrumentation/opencensus-specs/issues/123)). - -The `opencensus-contrib-log-correlation-log4j2` artifact provides a -[Log4j 2](https://logging.apache.org/log4j/2.x/) -[`ContextDataInjector`](https://logging.apache.org/log4j/2.x/manual/extending.html#Custom_ContextDataInjector) -that automatically adds tracing data to the context of Log4j -[`LogEvent`](https://logging.apache.org/log4j/2.x/log4j-core/apidocs/org/apache/logging/log4j/core/LogEvent.html)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()`](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](http://logging.apache.org/log4j/2.x/manual/lookups.html#ContextMapLookup). For -example, the trace ID can be accessed with `$${ctx:opencensusTraceId}`. The values can also be -accessed with the `X` conversion character in -[`PatternLayout`](http://logging.apache.org/log4j/2.x/manual/layouts.html#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. |