OpenCensus Stackdriver Log Correlation

This subproject is currently experimental, so it doesn't have any stability guarantees. It will remain experimental until we have a specification for a log correlation feature in opencensus-specs (issue #123).

The opencensus-contrib-log-correlation-stackdriver artifact provides a Stackdriver Logging LoggingEnhancer 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".

TODO(sebright): Add a demo to https://github.com/census-ecosystem/opencensus-experiments and link to it.

Instructions

Prerequisites

This log correlation feature requires a project that is using the com.google.cloud: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:

<dependencies>
  <dependency>
    <groupId>io.opencensus</groupId>
    <artifactId>opencensus-contrib-log-correlation-stackdriver</artifactId>
    <version>0.15.0</version>
    <scope>runtime</scope>
  </dependency>
</dependencies>

For Gradle add to your dependencies:

runtime 'io.opencensus:opencensus-contrib-log-correlation-stackdriver:0.15.0'

Configure the OpenCensusTraceLoggingEnhancer

Setting the project ID

By default, OpenCensusTraceLoggingEnhancer looks up the project ID from google-cloud-java. See here 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. It specifies the LoggingEnhancer class and sets both optional properties:

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

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. It specifies the LoggingEnhancer class and sets both optional 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

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