blob: a5bf1449fed23691c07e4b3879b489c15a59a306 (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
|
# 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.
|
