Document traceId/spanId injection into logs (#1339)

* Document traceId/spanId injection into logs

* Document traceId/spanId injection into logs

README.md

@@ -241,6 +241,7 @@ provide the path to a JAR file including an SPI implementation using the system
 | [khttp](https://khttp.readthedocs.io)                                                                                                 | 0.1+                           |
 | [Kubernetes Client](https://github.com/kubernetes-client/java)                                                                        | 7.0+                           |
 | [Lettuce](https://github.com/lettuce-io/lettuce-core)                                                                                 | 4.0+ (not including 6.x yet)   |
+| [Log4j 1](https://logging.apache.org/log4j/1.2/)                                                                                      | 1.2+                           |
 | [Log4j 2](https://logging.apache.org/log4j/2.x/)                                                                                      | 2.7+                           |
 | [Logback](http://logback.qos.ch/)                                                                                                     | 1.0+                           |
 | [MongoDB Drivers](https://mongodb.github.io/mongo-java-driver/)                                                                       | 3.3+                           |
@@ -290,6 +291,10 @@ you can enable it by add the following system property:
 
 See [Suppressing specific auto-instrumentation](docs/suppressing-instrumentation.md)
 
+### Logger MDC auto-instrumentation
+
+See [Logger MDC auto-instrumentation](docs/logger-mdc-instrumentation.md)
+
 ## Manually instrumenting
 
 > :warning: starting with 0.6.0, and prior to version 1.0.0, `opentelemetry-javaagent-all.jar`

docs/logger-mdc-instrumentation.md

@@ -0,0 +1,38 @@
+# Logger MDC auto-instrumentation
+
+The Mapped Diagnostic Context (MDC) is
+
+> an instrument for distinguishing interleaved log output from different sources.
+> &mdash; <cite> [log4j MDC documentation](http://logging.apache.org/log4j/1.2/apidocs/org/apache/log4j/MDC.html) </cite>
+
+It contains thread-local contextual information which is later copied to each logging event captured
+by a logging library.
+
+The OTel Java agent injects several pieces of information about the current span into each logging
+event's MDC copy:
+
+- `traceId` - the current trace id
+  (same as `TracingContextUtils.getCurrentSpan().getContext().getTraceIdAsHexString()`);
+- `spanId` - the current span id
+  (same as `TracingContextUtils.getCurrentSpan().getContext().getSpanIdAsHexString()`);
+- `sampled` - a boolean flag marking whether the current span is sampled or not
+  (same as `TracingContextUtils.getCurrentSpan().getContext().isSampled()`).
+  This flag is only added when `sampled` is `true`, for non-sampled spans MDC does not contain it at
+  all.
+
+Those three pieces of information can be included in log statements produced by the logging library
+by specifying them in the pattern/format. Example for Spring Boot configuration (which uses logback):
+
+```properties
+logging.pattern.console = %d{yyyy-MM-dd HH:mm:ss} - %logger{36} - %msg t:%X{traceId} s:%X{spanId} %n
+```
+
+This way any services or tools that parse the application logs can correlate traces/spans with log statements.
+
+## Supported logging libraries
+
+| Library | Version |
+|---------|---------|
+| Log4j 1 | 1.2+    |
+| Log4j 2 | 2.7+    |
+| Logback | 1.0+    |