1# OpenCensus Stackdriver Log Correlation 2 3The `opencensus-contrib-log-correlation-stackdriver` artifact provides a 4[Stackdriver Logging](https://cloud.google.com/logging/) 5[`LoggingEnhancer`](http://googlecloudplatform.github.io/google-cloud-java/google-cloud-clients/apidocs/com/google/cloud/logging/LoggingEnhancer.html) 6that automatically adds tracing data to log entries. The class name is 7`OpenCensusTraceLoggingEnhancer`. `OpenCensusTraceLoggingEnhancer` adds the current trace ID, span 8ID, and sampling decision to each log entry, which allows Stackdriver to display the log entries 9associated with each trace, or filter logs based on trace or span ID. 10 11## Instructions 12 13### Prerequisites 14 15This log correlation feature requires a project that is using the 16[`com.google.cloud:google-cloud-logging`](https://github.com/GoogleCloudPlatform/google-cloud-java/tree/master/google-cloud-clients/google-cloud-logging) 17library to export logs to Stackdriver. `google-cloud-logging` must be version `1.33.0` or later. 18The application can run on Google Cloud Platform, on-premise, or on 19another cloud platform. See https://cloud.google.com/logging/docs/setup/java for instructions for 20setting up `google-cloud-logging`. 21 22**Note that this artifact does not support logging done through the Stackdriver Logging agent.** 23 24### Add the dependencies to your project 25 26For Maven add to your `pom.xml`: 27```xml 28<dependencies> 29 <dependency> 30 <groupId>io.opencensus</groupId> 31 <artifactId>opencensus-contrib-log-correlation-stackdriver</artifactId> 32 <version>0.28.3</version> 33 <scope>runtime</scope> 34 </dependency> 35</dependencies> 36``` 37 38For Gradle add to your dependencies: 39```groovy 40runtime 'io.opencensus:opencensus-contrib-log-correlation-stackdriver:0.28.3' 41``` 42 43### Configure the `OpenCensusTraceLoggingEnhancer` 44 45#### Setting the project ID 46 47By default, `OpenCensusTraceLoggingEnhancer` looks up the project ID from `google-cloud-java`. See 48[here](https://github.com/GoogleCloudPlatform/google-cloud-java#specifying-a-project-id) for 49instructions for configuring the project ID with `google-cloud-java`. 50 51To override the project ID, set the following property as a system property or as a 52`java.util.logging` property: 53 54`io.opencensus.contrib.logcorrelation.stackdriver.OpenCensusTraceLoggingEnhancer.projectId` 55 56Other aspects of configuring the `OpenCensusTraceLoggingEnhancer` depend on the logging 57implementation and `google-cloud-logging` adapter in use. 58 59#### Logback with `google-cloud-logging-logback` `LoggingAppender` 60 61The `LoggingAppender` should already be configured in `logback.xml` as described in 62https://cloud.google.com/logging/docs/setup/java#logback_appender. Add 63"`io.opencensus.contrib.logcorrelation.stackdriver.OpenCensusTraceLoggingEnhancer`" to the list of 64enhancers. Optionally, set the `projectId` property described above as a system property. 65 66Here is an example `logback.xml`, based on the 67[`google-cloud-logging-logback` example](https://github.com/GoogleCloudPlatform/java-docs-samples/blob/a2b04b20d81ee631439a9368fb99b44849519e28/logging/logback/src/main/resources/logback.xml). 68It specifies the `LoggingEnhancer` class and sets the optional project ID property: 69 70```xml 71<configuration> 72 <property scope="system" name="io.opencensus.contrib.logcorrelation.stackdriver.OpenCensusTraceLoggingEnhancer.projectId" value="my-project-id" /> 73 <appender name="CLOUD" class="com.google.cloud.logging.logback.LoggingAppender"> 74 <enhancer>io.opencensus.contrib.logcorrelation.stackdriver.OpenCensusTraceLoggingEnhancer</enhancer> 75 </appender> 76 77 <root level="info"> 78 <appender-ref ref="CLOUD" /> 79 </root> 80</configuration> 81``` 82 83See 84https://github.com/census-ecosystem/opencensus-experiments/tree/master/java/log_correlation/stackdriver/logback 85for a full example. 86 87#### `java.util.logging` with `google-cloud-logging` `LoggingHandler` 88 89The `LoggingHandler` should already be configured in a logging `.properties` file, as described in 90https://cloud.google.com/logging/docs/setup/java#jul_handler. Add 91"`io.opencensus.contrib.logcorrelation.stackdriver.OpenCensusTraceLoggingEnhancer`" to the list of 92enhancers. Optionally, set the `projectId` property described above in the properties file. 93 94Here is an example `.properties` file, based on the 95[`google-cloud-logging` example](https://github.com/GoogleCloudPlatform/java-docs-samples/blob/a2b04b20d81ee631439a9368fb99b44849519e28/logging/jul/src/main/resources/logging.properties). 96It specifies the `LoggingEnhancer` class and sets the optional project ID property: 97 98```properties 99.level = INFO 100 101com.example.MyClass.handlers=com.google.cloud.logging.LoggingHandler 102 103com.google.cloud.logging.LoggingHandler.enhancers=io.opencensus.contrib.logcorrelation.stackdriver.OpenCensusTraceLoggingEnhancer 104io.opencensus.contrib.logcorrelation.stackdriver.OpenCensusTraceLoggingEnhancer.projectId=my-project-id 105``` 106 107See 108https://github.com/census-ecosystem/opencensus-experiments/tree/master/java/log_correlation/stackdriver/java_util_logging 109for a full example. 110 111#### Custom `google-cloud-logging` adapter 112 113The `google-cloud-logging` adapter needs to instantiate the `OpenCensusTraceLoggingEnhancer`, 114possibly by looking up the class name of the `LoggingEnhancer` in a configuration file and 115instantiating it with reflection. Then the adapter needs to call the `LoggingEnhancer`'s 116`enhanceLogEntry` method on all `LogEntry`s that will be passed to `google-cloud-logging`'s 117`Logging.write` method. `enhanceLogEntry` must be called in the same thread that executed the log 118statement, in order to provide the current trace and span ID. 119 120#### Java Versions 121 122Java 7 or above is required for using this artifact. 123