Document MDC log correlation support (#724)

* add documentation

Signed-off-by: avim <[email protected]>

* PR feedback

Co-authored-by: avim <[email protected]>

Author: avimas

jaeger-core/README.md

@@ -140,6 +140,62 @@ Tracer tracer = configuration
     .withMetricsFactory(metricsReporter)
     .build();
 ```
+### Log Correlation
+
+The Jaeger Java Client supports log correlation by updating the logging context (MDC) with
+three variables: `traceId`, `spanId`, `sampled`.  
+
+To accomplish that Jaegar Tracer should be created with the following two steps:
+
+1. Create the MDCScopeManager using either default MDC field names:
+
+   ```java
+    MDCScopeManager scopeManager = new MDCScopeManager.Builder().build()
+    ```
+    Or by providing optional custom names:
+    
+    ```java
+    MDCScopeManager scopeManager = new MDCScopeManager
+                                   .Builder()
+                                   .withMDCTraceIdKey("CustomTraceId")
+                                   .withMDCSampledKey("customSampled")
+                                   .withMDCSpanIdKey("customSpanId")
+                                   .build();
+    ```
+2. Create the Jaegar Tracer by supplying the MDCScopeManager created step 1:
+```java
+JaegerTracer.Builder("serviceName").withScopeManager(scopeManager).build();	
+```
+In order to have the trace info in the logs, a logging system offers MDC functionality such as log4j
+needs to be configured with an appender containing a proper PatternLayout.
+
+For example the following code:
+```java
+ Span parentSpan = tracer.buildSpan("log example").start();
+    try (Scope scope = tracer.activateSpan(parentSpan)) {
+      LOGGER.debug("Debug with trace context!!!");
+    }
+  }
+```
+With this log4j2.xml configuration:
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<Configuration status="INFO">
+    <Appenders>
+        <Console name="console" target="SYSTEM_OUT">
+            <PatternLayout
+                    pattern="[%-5level] %d{yyyy-MM-dd HH:mm:ss.SSS} [%t] %c{1} - %msg% traceId=%X{traceId} spanId=%X{spanId} sampled=%X{sampled}%n" />
+        </Console>
+    </Appenders>
+    <Loggers>
+        <Root level="debug" additivity="false">
+            <AppenderRef ref="console" />
+        </Root>
+    </Loggers>
+</Configuration>
+```
+Prints:  
+[DEBUG] 2020-06-28 22:25:07.152 [main] LogExample - Debug with trace context!!!% traceId=729b37ccf9c1549d spanId=729b37ccf9c1549d sampled=false
 
 ## Development