From 0125239a76ee87e34dbc79831ed3a0825b5ff35f Mon Sep 17 00:00:00 2001
From: Frank Chen <frankchn@dev-dsk-frankchn-2a-ff9871a5.us-west-2.amazon.com>
Date: Tue, 8 Sep 2026 20:19:36 +0000
Subject: [PATCH] docs(logging): document Java 2.x MDC keys

---
 docs/advanced/logging.md | 42 ++++++++++++++++++++++++++++++++++++----
 1 file changed, 38 insertions(+), 4 deletions(-)

diff --git a/docs/advanced/logging.md b/docs/advanced/logging.md
index fe4762235..2244a746a 100644
--- a/docs/advanced/logging.md
+++ b/docs/advanced/logging.md
@@ -27,14 +27,48 @@ Logs include execution context via MDC (works with any SLF4J-compatible logging
 {
   "timestamp": "2024-01-15T10:30:00.000Z",
   "level": "INFO",
-  "message": "Processing order: ORD-123",
-  "durableExecutionArn": "arn:aws:lambda:us-east-1:123456789:function:order-processor:exec-abc123",
+  "message": "Validating order details",
+  "executionArn": "arn:aws:lambda:us-east-1:123456789:function:order-processor:exec-abc123",
   "requestId": "a1b2c3d4-5678-90ab-cdef-example12345",
   "operationId": "1",
-  "operationName": "validate"
+  "operationName": "validate",
+  "attempt": "1"
 }
 ```
 
+Java SDK 2.x uses `executionArn`, `operationId`, and `operationName` by default.
+Applications migrating log queries or dashboards from 1.x can temporarily emit
+`durableExecutionArn`, `contextId`, and `contextName` instead:
+
+```java
+@Override
+protected DurableConfig createConfiguration() {
+    return DurableConfig.builder()
+        .withLoggerConfig(new LoggerConfig(true, true))
+        .build();
+}
+```
+
+The first argument controls replay suppression. The second enables the old MDC key
+names.
+
+### Custom SLF4J Delegate
+
+`getLogger()` uses the SDK's default SLF4J logger. Pass a specific SLF4J `Logger` to
+`getLogger(Logger delegate)` when you want the durable metadata and replay behavior
+applied to another logger:
+
+```java
+private static final Logger applicationLogger =
+    LoggerFactory.getLogger(OrderProcessor.class);
+
+var logger = ctx.getLogger(applicationLogger);
+logger.info("Processing order: {}", order.getId());
+```
+
+This creates a `DurableLogger` around the supplied delegate for that call. It does not
+replace the default returned by later parameterless `getLogger()` calls.
+
 ### Replay Behavior
 
 By default, logs are suppressed during replay to avoid duplicates:
@@ -59,4 +93,4 @@ protected DurableConfig createConfiguration() {
         .withLoggerConfig(LoggerConfig.withReplayLogging())
         .build();
 }
-```
\ No newline at end of file
+```