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
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
|
# OpenCensus Stackdriver 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-stackdriver` artifact provides a
[Stackdriver Logging](https://cloud.google.com/logging/)
[`LoggingEnhancer`](http://googlecloudplatform.github.io/google-cloud-java/google-cloud-clients/apidocs/com/google/cloud/logging/LoggingEnhancer.html)
that automatically adds tracing data to log entries. The class name is
`OpenCensusTraceLoggingEnhancer`. `OpenCensusTraceLoggingEnhancer` adds the current trace and span
ID to each log entry, which allows Stackdriver to display the log entries associated with each
trace, or filter logs based on trace or span ID. It currently also adds the sampling decision using
the label "`opencensusTraceSampled`".
## Instructions
### Prerequisites
This log correlation feature requires a project that is using the
[`com.google.cloud:google-cloud-logging`](https://github.com/GoogleCloudPlatform/google-cloud-java/tree/master/google-cloud-clients/google-cloud-logging)
library to export logs to Stackdriver. `google-cloud-logging` must be version `1.33.0` or later.
The application can run on Google Cloud Platform, on-premise, or on
another cloud platform. See https://cloud.google.com/logging/docs/setup/java for instructions for
setting up `google-cloud-logging`.
**Note that this artifact does not support logging done through the Stackdriver Logging agent.**
### 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-stackdriver</artifactId>
<version>0.16.0</version>
<scope>runtime</scope>
</dependency>
</dependencies>
```
For Gradle add to your dependencies:
```groovy
runtime 'io.opencensus:opencensus-contrib-log-correlation-stackdriver:0.16.0'
```
### Configure the `OpenCensusTraceLoggingEnhancer`
#### Setting the project ID
By default, `OpenCensusTraceLoggingEnhancer` looks up the project ID from `google-cloud-java`. See
[here](https://github.com/GoogleCloudPlatform/google-cloud-java#specifying-a-project-id) for
instructions for configuring the project ID with `google-cloud-java`.
To override the project ID, set the following property as a system property or as a
`java.util.logging` property:
`io.opencensus.contrib.logcorrelation.stackdriver.OpenCensusTraceLoggingEnhancer.projectId`
#### Choosing when to add tracing data to log entries
The following property controls the decision to add tracing data from the current span to a log
entry:
`io.opencensus.contrib.logcorrelation.stackdriver.OpenCensusTraceLoggingEnhancer.spanSelection`
The allowed values are:
* `ALL_SPANS`: adds tracing data to all log entries (default)
* `NO_SPANS`: disables the log correlation feature
* `SAMPLED_SPANS`: adds tracing data to log entries when the current span is sampled
Other aspects of configuring the `OpenCensusTraceLoggingEnhancer` depend on the logging
implementation and `google-cloud-logging` adapter in use.
#### Logback with `google-cloud-logging-logback` `LoggingAppender`
The `LoggingAppender` should already be configured in `logback.xml` as described in
https://cloud.google.com/logging/docs/setup/java#logback_appender. Add
"`io.opencensus.contrib.logcorrelation.stackdriver.OpenCensusTraceLoggingEnhancer`" to the list of
enhancers. Optionally, set the `spanSelection` and `projectId` properties described above as system
properties.
Here is an example `logback.xml`, based on the
[`google-cloud-logging-logback` example](https://github.com/GoogleCloudPlatform/java-docs-samples/blob/a2b04b20d81ee631439a9368fb99b44849519e28/logging/logback/src/main/resources/logback.xml).
It specifies the `LoggingEnhancer` class and sets both optional properties:
```xml
<configuration>
<property scope="system" name="io.opencensus.contrib.logcorrelation.stackdriver.OpenCensusTraceLoggingEnhancer.spanSelection" value="SAMPLED_SPANS" />
<property scope="system" name="io.opencensus.contrib.logcorrelation.stackdriver.OpenCensusTraceLoggingEnhancer.projectId" value="my-project-id" />
<appender name="CLOUD" class="com.google.cloud.logging.logback.LoggingAppender">
<enhancer>io.opencensus.contrib.logcorrelation.stackdriver.OpenCensusTraceLoggingEnhancer</enhancer>
</appender>
<root level="info">
<appender-ref ref="CLOUD" />
</root>
</configuration>
```
See
https://github.com/census-ecosystem/opencensus-experiments/tree/master/java/log_correlation/stackdriver/logback
for a full example.
#### `java.util.logging` with `google-cloud-logging` `LoggingHandler`
The `LoggingHandler` should already be configured in a logging `.properties` file, as described in
https://cloud.google.com/logging/docs/setup/java#jul_handler. Add
"`io.opencensus.contrib.logcorrelation.stackdriver.OpenCensusTraceLoggingEnhancer`" to the list of
enhancers. Optionally, set the `spanSelection` and `projectId` properties described above in the
properties file.
Here is an example `.properties` file, based on the
[`google-cloud-logging` example](https://github.com/GoogleCloudPlatform/java-docs-samples/blob/a2b04b20d81ee631439a9368fb99b44849519e28/logging/jul/src/main/resources/logging.properties).
It specifies the `LoggingEnhancer` class and sets both optional properties:
```properties
.level = INFO
com.example.MyClass.handlers=com.google.cloud.logging.LoggingHandler
com.google.cloud.logging.LoggingHandler.enhancers=io.opencensus.contrib.logcorrelation.stackdriver.OpenCensusTraceLoggingEnhancer
io.opencensus.contrib.logcorrelation.stackdriver.OpenCensusTraceLoggingEnhancer.spanSelection=SAMPLED_SPANS
io.opencensus.contrib.logcorrelation.stackdriver.OpenCensusTraceLoggingEnhancer.projectId=my-project-id
```
See
https://github.com/census-ecosystem/opencensus-experiments/tree/master/java/log_correlation/stackdriver/java_util_logging
for a full example.
#### Custom `google-cloud-logging` adapter
The `google-cloud-logging` adapter needs to instantiate the `OpenCensusTraceLoggingEnhancer`,
possibly by looking up the class name of the `LoggingEnhancer` in a configuration file and
instantiating it with reflection. Then the adapter needs to call the `LoggingEnhancer`'s
`enhanceLogEntry` method on all `LogEntry`s that will be passed to `google-cloud-logging`'s
`Logging.write` method. `enhanceLogEntry` must be called in the same thread that executed the log
statement, in order to provide the current trace and span ID.
#### Java Versions
Java 7 or above is required for using this artifact.
|
