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