# 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 io.opencensus opencensus-contrib-log-correlation-stackdriver 0.16.1 runtime ``` For Gradle add to your dependencies: ```groovy runtime 'io.opencensus:opencensus-contrib-log-correlation-stackdriver:0.16.1' ``` ### 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 io.opencensus.contrib.logcorrelation.stackdriver.OpenCensusTraceLoggingEnhancer ``` 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.