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.