1 # OpenCensus Stackdriver Log Correlation 2 3 This subproject is currently experimental, so it may be redesigned or removed in the future. It 4 will 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 8 The `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) 11 that automatically adds tracing data to log entries. The class name is 12 `OpenCensusTraceLoggingEnhancer`. `OpenCensusTraceLoggingEnhancer` adds the current trace and span 13 ID to each log entry, which allows Stackdriver to display the log entries associated with each 14 trace, or filter logs based on trace or span ID. It currently also adds the sampling decision using 15 the label "`opencensusTraceSampled`". 16 17 ## Instructions 18 19 ### Prerequisites 20 21 This 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) 23 library to export logs to Stackdriver. `google-cloud-logging` must be version `1.33.0` or later. 24 The application can run on Google Cloud Platform, on-premise, or on 25 another cloud platform. See https://cloud.google.com/logging/docs/setup/java for instructions for 26 setting 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 32 For 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 44 For Gradle add to your dependencies: 45 ```groovy 46 runtime 'io.opencensus:opencensus-contrib-log-correlation-stackdriver:0.16.1' 47 ``` 48 49 ### Configure the `OpenCensusTraceLoggingEnhancer` 50 51 #### Setting the project ID 52 53 By 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 55 instructions for configuring the project ID with `google-cloud-java`. 56 57 To 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 64 The following property controls the decision to add tracing data from the current span to a log 65 entry: 66 67 `io.opencensus.contrib.logcorrelation.stackdriver.OpenCensusTraceLoggingEnhancer.spanSelection` 68 69 The 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 77 Other aspects of configuring the `OpenCensusTraceLoggingEnhancer` depend on the logging 78 implementation and `google-cloud-logging` adapter in use. 79 80 #### Logback with `google-cloud-logging-logback` `LoggingAppender` 81 82 The `LoggingAppender` should already be configured in `logback.xml` as described in 83 https://cloud.google.com/logging/docs/setup/java#logback_appender. Add 84 "`io.opencensus.contrib.logcorrelation.stackdriver.OpenCensusTraceLoggingEnhancer`" to the list of 85 enhancers. Optionally, set the `spanSelection` and `projectId` properties described above as system 86 properties. 87 88 Here 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). 90 It 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 106 See 107 https://github.com/census-ecosystem/opencensus-experiments/tree/master/java/log_correlation/stackdriver/logback 108 for a full example. 109 110 #### `java.util.logging` with `google-cloud-logging` `LoggingHandler` 111 112 The `LoggingHandler` should already be configured in a logging `.properties` file, as described in 113 https://cloud.google.com/logging/docs/setup/java#jul_handler. Add 114 "`io.opencensus.contrib.logcorrelation.stackdriver.OpenCensusTraceLoggingEnhancer`" to the list of 115 enhancers. Optionally, set the `spanSelection` and `projectId` properties described above in the 116 properties file. 117 118 Here 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). 120 It specifies the `LoggingEnhancer` class and sets both optional properties: 121 122 ```properties 123 .level = INFO 124 125 com.example.MyClass.handlers=com.google.cloud.logging.LoggingHandler 126 127 com.google.cloud.logging.LoggingHandler.enhancers=io.opencensus.contrib.logcorrelation.stackdriver.OpenCensusTraceLoggingEnhancer 128 io.opencensus.contrib.logcorrelation.stackdriver.OpenCensusTraceLoggingEnhancer.spanSelection=SAMPLED_SPANS 129 io.opencensus.contrib.logcorrelation.stackdriver.OpenCensusTraceLoggingEnhancer.projectId=my-project-id 130 ``` 131 132 See 133 https://github.com/census-ecosystem/opencensus-experiments/tree/master/java/log_correlation/stackdriver/java_util_logging 134 for a full example. 135 136 #### Custom `google-cloud-logging` adapter 137 138 The `google-cloud-logging` adapter needs to instantiate the `OpenCensusTraceLoggingEnhancer`, 139 possibly by looking up the class name of the `LoggingEnhancer` in a configuration file and 140 instantiating 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 143 statement, in order to provide the current trace and span ID. 144 145 #### Java Versions 146 147 Java 7 or above is required for using this artifact. 148
