Add specification of log correlation for tracing (issue census-instru…

…mentation#123).

The specification only covers aspects of log correlation that are likely to be
shared by log correlation implementations for multiple languages and logging
frameworks.  It is based on the experimental log correlation libraries in
opencensus-java:

https://github.com/census-instrumentation/opencensus-java/tree/master/contrib/log_correlation/stackdriver
https://github.com/census-instrumentation/opencensus-java/tree/master/contrib/log_correlation/log4j2

trace/LogCorrelation.md

@@ -0,0 +1,59 @@
+# Log Correlation
+
+Log correlation is a feature that inserts information about the current span into log entries
+created by existing logging frameworks.  The feature can be used to add more context to log entries,
+filter log entries by trace ID, or show log entries as annotations on a trace.
+
+The design of a log correlation implementation depends heavily on the details of the particular
+logging framework that it supports.  Therefore, this document only covers the aspects of log
+correlation that could be shared across log correlation implementations for multiple languages and
+logging frameworks.  It doesn't cover how to hook into the logging framework.
+
+## Tracing data to include in log entries
+
+A log correlation implementation should insert the following pieces of tracing data from the current
+span context into each log entry:
+
+### Trace ID
+
+The trace ID of the current span.  See Span.md#traceid.
+
+### Span ID
+
+The span ID of the current span.  See Span.md#spanid.
+
+### Sampling Decision
+
+The sampling bit of the current span, as a boolean.  See Span.md#supported-bits.
+
+## String format for tracing data
+
+The logging framework may require the pieces of tracing data to be converted to strings.  In that
+case, the log correlation implementation should format the trace ID and span ID as lowercase base 16
+and format the sampling decision as "true" or "false".
+
+## Key names for tracing data
+
+Some logging frameworks allow the insertion of arbitrary key-value pairs into log entries.  When
+a log correlation implementation inserts tracing data by that method, the keys names should be
+"opencensusTraceId", "opencensusSpanId", and "opencensusTraceSampled" by default.  The log
+correlation implementation may allow the user to override the tracing data key names.
+
+## Deciding when to add tracing data to a log entry
+
+The log correlation implementation may allow the user to configure the choice to add tracing data to
+a log entry.  This configuration option should be called "span selection", and it should have the
+following values:
+
+### All Spans
+
+Always add tracing data to log entries, even when the current span is not sampled.  This is the
+default.
+
+### Sampled Spans
+
+Add tracing data to a log entry iff the current span is sampled.
+
+### No Spans
+
+Never add tracing data to log entries.  This option disables the log correlation feature.