Expand readme for opencensus-contrib-log-correlation-stackdriver.

1 files changed, 137 insertions, 5 deletions

diff --git a/contrib/log_correlation/stackdriver/README.md b/contrib/log_correlation/stackdriver/README.md
index b88da9f7..fcc08585 100644
--- a/contrib/log_correlation/stackdriver/README.md
+++ b/contrib/log_correlation/stackdriver/README.md
@@ -1,10 +1,142 @@
 # OpenCensus Stackdriver Log Correlation
 
-This subproject is currently experimental. It provides a Stackdriver 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 LoggingEnhancer adds the trace ID, which
-allows Stackdriver to display log entries associated with each trace or filter logs based on trace
-ID. It currently also adds the span ID and sampling decision.
+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](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`".
 
 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`](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.14.0</version>
+    <scope>runtime</scope>
+  </dependency>
+</dependencies>
+```
+
+For Gradle add to your dependencies:
+```groovy
+runtime 'io.opencensus:opencensus-contrib-log-correlation-stackdriver:0.14.0'
+```
+
+### 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>
+```
+
+#### `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
+```
+
+#### 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.