# 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.1</version>
    <scope>runtime</scope>
  </dependency>
</dependencies>
```

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
<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.