From 598cbb8f1b463837354daa1b94f4f2359254d46d Mon Sep 17 00:00:00 2001
From: sebright <sebright@google.com>
Date: Mon, 8 Oct 2018 20:21:24 -0700
Subject: [PATCH] Add specification of log correlation for tracing (issue
 #123). (#181)

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 | 58 +++++++++++++++++++++++++++++++++++++++++
 trace/README.md         |  1 +
 2 files changed, 59 insertions(+)
 create mode 100644 trace/LogCorrelation.md

diff --git a/trace/LogCorrelation.md b/trace/LogCorrelation.md
new file mode 100644
index 0000000..a0d5039
--- /dev/null
+++ b/trace/LogCorrelation.md
@@ -0,0 +1,58 @@
+# Log Correlation (draft)
+
+This specification is not done until the key names below are finalized (issue
+[#195](https://github.com/census-instrumentation/opencensus-specs/issues/195)).
+
+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 find log entries associated with a specific trace or span.
+
+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.
+
+## Identifying the span to associate with a log entry
+
+A log correlation implementation should look up tracing data from the span that is current at the
+point of the log statement.  See
+[Span.md#how-span-interacts-with-context](Span.md#how-span-interacts-with-context) for the
+definition of the current span.
+
+## Tracing data to include in log entries
+
+A log correlation implementation should make the following pieces of tracing data from the current
+span context available in each log entry:
+
+### Trace ID
+
+The trace ID of the current span.  See [Span.md#traceid](Span.md#traceid).
+
+### Span ID
+
+The span ID of the current span.  See [Span.md#spanid](Span.md#spanid).
+
+### Sampling Decision
+
+The sampling bit of the current span, as a boolean.  See
+[Span.md#supported-bits](Span.md#supported-bits).
+
+TODO(sebright): Include "samplingScore" once that field is added to the SpanContext.
+
+TODO(sebright): Add a section on fields from the Tracestate. Users should be able to add
+vendor-specific fields from the Tracestate to logs, using a callback mechanism.
+
+TODO(sebright): Consider adding parent span ID, to allow recreating the trace structure from logs.
+
+## 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 key names should be
+"opencensusTraceId", "opencensusSpanId", and "opencensusTraceSampled" by default.  The log
+correlation implementation may allow the user to override the tracing data key names.
diff --git a/trace/README.md b/trace/README.md
index 895971d..277bb3b 100644
--- a/trace/README.md
+++ b/trace/README.md
@@ -10,3 +10,4 @@ describes the key types and the overall behavior.
 * [gRPC integration](gRPC.md): document about how to instrument gRPC framework.
 * [HTTP integration](HTTP.md): document about how to instrument http frameworks.
 * [Sampling logic](Sampling.md): document about how sampling works.
+* [Log correlation](LogCorrelation.md): specification for a feature for inserting tracing data into log entries.