docs: logging

- Restructure page with clear section order: log methods, default
  log format, execution metadata, replay suppression, custom logger,
  configure logger, logger interface, and Powertools
- Add per-language default log format examples with JSON output
- Add execution metadata section with per-context field reference
  and per-language tabs for child context fields
- Clarify replay suppression behaviour including retrying steps
- Add Configure logger and Logger interface as separate sections
- Add Powertools for AWS Lambda section with drop-in examples for
  all three languages
- Fix opening paragraph to be language-neutral
- Remove emdashes from list items

Closes #37, Closes #73, Closes #55

Author: yaythomas

docs/sdk-reference/observability/logging.md

@@ -0,0 +1,14 @@
+import software.amazon.lambda.durable.DurableContext;
+import software.amazon.lambda.durable.DurableHandler;
+
+public class BasicUsage extends DurableHandler<Object, String> {
+    @Override
+    public String handleRequest(Object event, DurableContext context) {
+        context.getLogger().info("Starting workflow");
+
+        String result = context.step("process", String.class, stepCtx -> "done");
+
+        context.getLogger().info("Workflow complete: {}", result);
+        return result;
+    }
+}

examples/java/sdk-reference/observability/basic-usage.java

@@ -0,0 +1,21 @@
+import software.amazon.lambda.durable.DurableConfig;
+import software.amazon.lambda.durable.DurableContext;
+import software.amazon.lambda.durable.DurableHandler;
+import software.amazon.lambda.durable.logging.LoggerConfig;
+
+public class CustomLogger extends DurableHandler<Object, Void> {
+
+    @Override
+    protected DurableConfig createConfiguration() {
+        // Allow logs during replay by overriding the default LoggerConfig.
+        return DurableConfig.builder()
+                .withLoggerConfig(LoggerConfig.withReplayLogging())
+                .build();
+    }
+
+    @Override
+    public Void handleRequest(Object event, DurableContext context) {
+        context.getLogger().info("Logs appear on every replay");
+        return null;
+    }
+}

examples/java/sdk-reference/observability/custom-logger.java

@@ -0,0 +1,17 @@
+import org.slf4j.Logger;
+import software.amazon.lambda.durable.logging.DurableLogger;
+
+// DurableLogger wraps an SLF4J Logger and adds MDC entries:
+//   durableExecutionArn, requestId, operationId, operationName, attempt
+//
+// Obtain it from any context:
+//   DurableLogger logger = context.getLogger();
+//   DurableLogger logger = stepContext.getLogger();
+//
+// Available methods:
+//   logger.trace(String format, Object... args)
+//   logger.debug(String format, Object... args)
+//   logger.info(String format, Object... args)
+//   logger.warn(String format, Object... args)
+//   logger.error(String format, Object... args)
+//   logger.error(String message, Throwable t)

examples/java/sdk-reference/observability/logger-interface.java

@@ -0,0 +1,16 @@
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import software.amazon.lambda.powertools.logging.Logging;
+import com.amazonaws.services.lambda.runtime.Context;
+import com.amazonaws.services.lambda.runtime.RequestHandler;
+
+public class MyHandler implements RequestHandler<Object, String> {
+
+    private static final Logger logger = LoggerFactory.getLogger(MyHandler.class);
+
+    @Logging
+    public String handleRequest(Object event, Context context) {
+        logger.info("Running handler");
+        return "ok";
+    }
+}

examples/java/sdk-reference/observability/powertools-logger.java

@@ -0,0 +1,16 @@
+import software.amazon.lambda.durable.DurableContext;
+import software.amazon.lambda.durable.DurableHandler;
+
+public class ReplaySuppression extends DurableHandler<Object, String> {
+    @Override
+    public String handleRequest(Object event, DurableContext context) {
+        // context.getLogger() suppresses duplicate logs during replay by default.
+        // Logs from completed operations do not repeat when the SDK replays.
+        context.getLogger().info("Step 1 starting");
+
+        String result = context.step("step-1", String.class, stepCtx -> "result");
+
+        context.getLogger().info("Step 1 complete: {}", result);
+        return result;
+    }
+}

examples/java/sdk-reference/observability/replay-suppression.java

@@ -0,0 +1,14 @@
+import software.amazon.lambda.durable.DurableContext;
+import software.amazon.lambda.durable.DurableHandler;
+import software.amazon.lambda.durable.StepContext;
+
+public class StepContextLogger extends DurableHandler<Object, String> {
+    @Override
+    public String handleRequest(Object event, DurableContext context) {
+        return context.step("process", String.class, (StepContext stepCtx) -> {
+            // stepCtx.getLogger() includes operationId, operationName, and attempt in MDC.
+            stepCtx.getLogger().info("Running step");
+            return "done";
+        });
+    }
+}

examples/java/sdk-reference/observability/step-context-logger.java

@@ -0,0 +1,11 @@
+from aws_durable_execution_sdk_python import DurableContext, durable_execution
+
+
+@durable_execution
+def handler(event: dict, context: DurableContext):
+    context.logger.info("Starting workflow")
+
+    result = context.step(lambda ctx: "done")
+
+    context.logger.info("Workflow complete", extra={"result": result})
+    return result

examples/python/sdk-reference/observability/basic-usage.py

@@ -0,0 +1,11 @@
+from aws_lambda_powertools import Logger
+
+from aws_durable_execution_sdk_python import DurableContext, durable_execution
+
+powertools_logger = Logger(service="my-service")
+
+
+@durable_execution
+def handler(event: dict, context: DurableContext):
+    context.set_logger(powertools_logger)
+    context.logger.info("Using Powertools logger")

examples/python/sdk-reference/observability/custom-logger.py

@@ -0,0 +1,24 @@
+from collections.abc import Mapping
+from typing import Protocol
+
+
+class LoggerInterface(Protocol):
+    def debug(
+        self, msg: object, *args: object, extra: Mapping[str, object] | None = None
+    ) -> None: ...
+
+    def info(
+        self, msg: object, *args: object, extra: Mapping[str, object] | None = None
+    ) -> None: ...
+
+    def warning(
+        self, msg: object, *args: object, extra: Mapping[str, object] | None = None
+    ) -> None: ...
+
+    def error(
+        self, msg: object, *args: object, extra: Mapping[str, object] | None = None
+    ) -> None: ...
+
+    def exception(
+        self, msg: object, *args: object, extra: Mapping[str, object] | None = None
+    ) -> None: ...