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 ID, span
ID, and sampling decision 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.
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.
For Maven add to your pom.xml
:
<dependencies>
<dependency>
<groupId>io.opencensus</groupId>
<artifactId>opencensus-contrib-log-correlation-stackdriver</artifactId>
<version>0.26.0</version>
<scope>runtime</scope>
</dependency>
</dependencies>
For Gradle add to your dependencies:
runtime 'io.opencensus:opencensus-contrib-log-correlation-stackdriver:0.26.0'
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
Other aspects of configuring the OpenCensusTraceLoggingEnhancer
depend on the logging
implementation and google-cloud-logging
adapter in use.
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 projectId
property described above as a system property.
Here is an example logback.xml
, based on the
google-cloud-logging-logback
example.
It specifies the LoggingEnhancer
class and sets the optional project ID property:
<configuration>
<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.
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 projectId
property 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 the optional project ID property:
.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.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.
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 7 or above is required for using this artifact.