Add easier discoverability and clarity to the MDC appender docs (#8638)

Co-authored-by: opentelemetrybot <107717825+opentelemetrybot@users.noreply.github.com>

docs/logger-mdc-instrumentation.md

@@ -19,21 +19,27 @@ event's MDC copy:
   (same as `Span.current().getSpanContext().getTraceFlags().asHex()`).
 
 Those three pieces of information can be included in log statements produced by the logging library
-by specifying them in the pattern/format.
+by specifying them in the pattern/format. This way any services or tools that parse the application
+logs can correlate traces/spans with log statements.
 
-Tip: for Spring Boot configuration which uses logback, you can add MDC to log lines by overriding only the `logging.pattern.level`:
+> Note: If the current `Span` is invalid, the OpenTelemetry appender will not inject any trace information.
 
-```properties
-logging.pattern.level = trace_id=%mdc{trace_id} span_id=%mdc{span_id} trace_flags=%mdc{trace_flags} %5p
-```
+## Supported logging libraries
 
-This way any services or tools that parse the application logs can correlate traces/spans with log
-statements.
+> Note: There are also log appenders for exporting logs to OpenTelemetry, not to be confused with the MDC appenders.
 
-## Supported logging libraries
+| Library | Auto-instrumented versions | Standalone Library Instrumentation                                                   |
+|---------|----------------------------|--------------------------------------------------------------------------------------|
+| Log4j 1 | 1.2+                       |                                                                                      |
+| Log4j 2 | 2.7+                       | [opentelemetry-log4j-context-data-2.17-autoconfigure](../instrumentation/log4j/log4j-context-data/log4j-context-data-2.17/library-autoconfigure) |                                                                                     |
+| Logback | 1.0+                       | [opentelemetry-logback-mdc-1.0](../instrumentation/logback/logback-mdc-1.0/library)  |
+
+## Frameworks
 
-| Library | Version |
-|---------|---------|
-| Log4j 1 | 1.2+    |
-| Log4j 2 | 2.7+    |
-| Logback | 1.0+    |
+### Spring Boot
+
+For Spring Boot configuration which uses logback, you can add MDC to log lines by overriding only the `logging.pattern.level`:
+
+```properties
+logging.pattern.level = trace_id=%mdc{trace_id} span_id=%mdc{span_id} trace_flags=%mdc{trace_flags} %5p
+```

instrumentation/logback/logback-mdc-1.0/library/README.md

@@ -32,7 +32,7 @@ dependencies {
 
 ### Usage
 
-logback.xml:
+The following demonstrates how you might configure the appender in your `logback.xml` configuration:
 
 ```xml
 <?xml version="1.0" encoding="UTF-8"?>
@@ -47,10 +47,18 @@ logback.xml:
   <appender name="OTEL" class="io.opentelemetry.instrumentation.logback.mdc.v1_0.OpenTelemetryAppender">
     <appender-ref ref="CONSOLE"/>
   </appender>
-  ...
+
+  <!-- Use the wrapped "OTEL" appender instead of the original "CONSOLE" one -->
+  <root level="INFO">
+    <appender-ref ref="OTEL"/>
+  </root>
+
 </configuration>
 ```
 
+> It's important to note you can also use other encoders in the `ConsoleAppender` like [logstash-logback-encoder](https://github.com/logfellow/logstash-logback-encoder).
+  This can be helpful when the `Span` is invalid and the `trace_id`, `span_id`, and `trace_flags` are all `null` and are hidden entirely from the logs.
+
 Logging events will automatically have context information from the span context injected. The
 following attributes are available for use: