feat(sdk): implement structured JSON logging for default logger (#304)

*Description of changes:*

- Replace unstructured console.log output with proper JSON format
- Fix default logger to output single JSON object per log entry
- Use appropriate console methods (info, error, warn, debug) for each
log level
- Add TypeScript documentation with examples and circular reference
warnings
- Maintain backward compatibility with custom loggers (AWS Powertools,
Winston, etc.)
- Remove unnecessary fallback logic since context logger always provides
structured data
- Update tests to verify structured JSON output format

This resolves the issue where logs were producing nested/duplicated
strings instead of clean structured JSON that AWS Lambda can properly
parse and log aggregators can query efficiently.

*Issue #, if available:*
#302

Author: ParidelPooya

packages/aws-durable-execution-sdk-js/src/types/durable-context.ts

@@ -28,8 +28,43 @@ export interface DurableContext {
    * The underlying AWS Lambda context
    */
   lambdaContext: Context;
+  
   /**
-   * Logger instance for this context, enriched with execution context information
+   * Logger instance for this context, automatically enriched with durable execution metadata.
+   * 
+   * **Automatic Enrichment:**
+   * All log entries are automatically enhanced with:
+   * - `timestamp`: ISO timestamp of the log entry
+   * - `execution_arn`: Durable execution ARN for tracing
+   * - `step_id`: Current step identifier (when logging from within a step)
+   * - `level`: Log level (info, error, warn, debug)
+   * - `message`: The log message
+   * 
+   * **Output Format:**
+   * ```json
+   * {
+   *   "timestamp": "2025-11-21T18:39:24.743Z",
+   *   "execution_arn": "arn:aws:lambda:...",
+   *   "level": "info", 
+   *   "step_id": "abc123",
+   *   "message": "User action completed",
+   *   "data": { "userId": "123", "action": "login" }
+   * }
+   * ```
+   * 
+   * @example
+   * ```typescript
+   * // Basic usage
+   * context.logger.info("User logged in", { userId: "123" });
+   * 
+   * // Error logging
+   * context.logger.error("Database connection failed", error, { retryCount: 3 });
+   * 
+   * // With custom logger (handles circular refs)
+   * import { Logger } from '@aws-lambda-powertools/logger';
+   * const powertoolsLogger = new Logger();
+   * context.configureLogger({ customLogger: powertoolsLogger });
+   * ```
    */
   logger: Logger;
 

packages/aws-durable-execution-sdk-js/src/types/logger.ts

@@ -1,17 +1,51 @@
 /**
- * Generic logger interface for custom logger implementations
- * Provides structured logging capabilities for durable execution contexts
+ * Generic logger interface for custom logger implementations.
+ * Provides structured logging capabilities for durable execution contexts.
+ * 
+ * When used through DurableContext, all log entries are automatically enriched
+ * with execution metadata (timestamp, execution_arn, step_id, etc.).
  */
 export interface Logger {
-  /** Generic log method with configurable level (optional for compatibility with popular loggers) */
+  /** 
+   * Generic log method with configurable level (optional for compatibility with popular loggers)
+   * @param level - Log level (e.g., "info", "error", "warn", "debug")
+   * @param message - Log message
+   * @param data - Additional structured data to include in log entry
+   * @param error - Error object (for error-level logs)
+   */
   log?(level: string, message?: string, data?: unknown, error?: Error): void;
-  /** Log error messages with optional error object and additional data */
+  
+  /** 
+   * Log error messages with optional error object and additional data
+   * @param message - Error description
+   * @param error - Error object with stack trace
+   * @param data - Additional context data
+   * @example context.logger.error("Database query failed", dbError, \{ query: "SELECT * FROM users" \})
+   */
   error(message?: string, error?: Error, data?: unknown): void;
-  /** Log warning messages with optional additional data */
+  
+  /** 
+   * Log warning messages with optional additional data
+   * @param message - Warning message
+   * @param data - Additional context data
+   * @example context.logger.warn("Rate limit approaching", \{ currentRate: 95, limit: 100 \})
+   */
   warn(message?: string, data?: unknown): void;
-  /** Log informational messages with optional additional data */
+  
+  /** 
+   * Log informational messages with optional additional data
+   * @param message - Information message
+   * @param data - Additional context data
+   * @example context.logger.info("User action completed", \{ userId: "123", action: "login" \})
+   */
   info(message?: string, data?: unknown): void;
-  /** Log debug messages with optional additional data */
+  
+  /** 
+   * Log debug messages with optional additional data
+   * @param message - Debug message
+   * @param data - Additional context data
+   * @example context.logger.debug("Processing step", \{ stepName: "validation", duration: 150 \})
+   */
   debug(message?: string, data?: unknown): void;
 }
 

packages/aws-durable-execution-sdk-js/src/utils/logger/default-logger.test.ts

@@ -1,14 +1,26 @@
 import { createDefaultLogger } from "./default-logger";
 
 describe("Default Logger", () => {
-  let consoleSpy: jest.SpyInstance;
+  let consoleSpies: {
+    log: jest.SpyInstance;
+    info: jest.SpyInstance;
+    error: jest.SpyInstance;
+    warn: jest.SpyInstance;
+    debug: jest.SpyInstance;
+  };
 
   beforeEach(() => {
-    consoleSpy = jest.spyOn(console, "log").mockImplementation();
+    consoleSpies = {
+      log: jest.spyOn(console, "log").mockImplementation(),
+      info: jest.spyOn(console, "info").mockImplementation(),
+      error: jest.spyOn(console, "error").mockImplementation(),
+      warn: jest.spyOn(console, "warn").mockImplementation(),
+      debug: jest.spyOn(console, "debug").mockImplementation(),
+    };
   });
 
   afterEach(() => {
-    consoleSpy.mockRestore();
+    Object.values(consoleSpies).forEach(spy => spy.mockRestore());
   });
 
   it("should create a logger with all required methods", () => {
@@ -21,60 +33,35 @@ describe("Default Logger", () => {
     expect(logger).toHaveProperty("debug");
   });
 
-  it("should log with custom level and all parameters", () => {
+  it("should output structured data using appropriate console methods", () => {
     const logger = createDefaultLogger();
-    const testData = { key: "value" };
-    const testError = new Error("test error");
+    const structuredData = {
+      timestamp: "2025-11-21T18:33:33.938Z",
+      execution_arn: "test-arn",
+      level: "info",
+      step_id: "abc123",
+      message: "structured message",
+    };
 
-    logger.log?.("custom", "test message", testData, testError);
+    logger.info("structured message", structuredData);
 
-    expect(consoleSpy).toHaveBeenCalledWith(
-      "custom",
-      "test message",
-      testData,
-      testError,
-    );
+    expect(consoleSpies.info).toHaveBeenCalledWith(structuredData);
   });
 
-  it("should log info messages", () => {
+  it("should use correct console methods for each log level", () => {
     const logger = createDefaultLogger();
-    const testData = { info: "data" };
+    const testData = { test: "data" };
 
+    logger.log?.("custom", "test message", testData);
     logger.info("info message", testData);
-
-    expect(consoleSpy).toHaveBeenCalledWith("info", "info message", testData);
-  });
-
-  it("should log error messages", () => {
-    const logger = createDefaultLogger();
-    const testError = new Error("test error");
-    const testData = { error: "data" };
-
-    logger.error("error message", testError, testData);
-
-    expect(consoleSpy).toHaveBeenCalledWith(
-      "error",
-      "error message",
-      testError,
-      testData,
-    );
-  });
-
-  it("should log warn messages", () => {
-    const logger = createDefaultLogger();
-    const testData = { warn: "data" };
-
+    logger.error("error message", new Error("test"), testData);
     logger.warn("warn message", testData);
-
-    expect(consoleSpy).toHaveBeenCalledWith("warn", "warn message", testData);
-  });
-
-  it("should log debug messages", () => {
-    const logger = createDefaultLogger();
-    const testData = { debug: "data" };
-
     logger.debug("debug message", testData);
 
-    expect(consoleSpy).toHaveBeenCalledWith("debug", "debug message", testData);
+    expect(consoleSpies.log).toHaveBeenCalledWith(testData);
+    expect(consoleSpies.info).toHaveBeenCalledWith(testData);
+    expect(consoleSpies.error).toHaveBeenCalledWith(testData);
+    expect(consoleSpies.warn).toHaveBeenCalledWith(testData);
+    expect(consoleSpies.debug).toHaveBeenCalledWith(testData);
   });
 });

packages/aws-durable-execution-sdk-js/src/utils/logger/default-logger.ts

@@ -1,20 +1,29 @@
 import { Logger } from "../../types";
 
 /**
- * Creates a default logger that outputs to console.
+ * Creates a default logger that outputs structured logs to console.
  * Used as fallback when no custom logger is provided.
+ * Always expects structured data from context logger.
+ * 
+ * Note: _message parameters are unused because the message is already included
+ * in the structured data object. Parameters are kept for Logger interface compatibility.
  */
 /* eslint-disable no-console */
 export const createDefaultLogger = (): Logger => ({
-  log: (level: string, message?: string, data?: unknown, error?: Error) =>
-    console.log(level, message, data, error),
-  info: (message?: string, data?: unknown) =>
-    console.log("info", message, data),
-  error: (message?: string, error?: Error, data?: unknown) =>
-    console.log("error", message, error, data),
-  warn: (message?: string, data?: unknown) =>
-    console.log("warn", message, data),
-  debug: (message?: string, data?: unknown) =>
-    console.log("debug", message, data),
+  log: (_level: string, _message?: string, data?: unknown, _error?: Error): void => {
+    console.log(data);
+  },
+  info: (_message?: string, data?: unknown): void => {
+    console.info(data);
+  },
+  error: (_message?: string, _error?: Error, data?: unknown): void => {
+    console.error(data);
+  },
+  warn: (_message?: string, data?: unknown): void => {
+    console.warn(data);
+  },
+  debug: (_message?: string, data?: unknown): void => {
+    console.debug(data);
+  },
 });
 /* eslint-enable no-console */