Feature request: Request and response logging in debug mode for Event Handler

[dreamorosi]

Use case

When developing and debugging REST APIs using the Event Handler, developers often need to inspect incoming requests and outgoing responses to troubleshoot issues, validate data transformations, and understand the flow of data through their Lambda functions.

Currently, the Event Handler's debug mode (POWERTOOLS_DEV=true) only enhances error responses with detailed stack traces and error information. However, there's no built-in way to automatically log request and response details during development, forcing developers to manually add logging statements throughout their route handlers. This feature would be for development use only and should never be enabled in production environments.

This creates several challenges:

• Manual logging overhead: Developers must remember to add request/response logging to each route handler
• Inconsistent logging: Different developers may log different aspects of requests/responses
• Debugging difficulty: Without automatic logging, it's harder to trace request flow and identify issues
• Development friction: Extra boilerplate code needed for basic debugging functionality

Solution/User Experience

When POWERTOOLS_DEV=true is enabled, the Event Handler should automatically log incoming requests and outgoing responses at an appropriate log level (e.g., DEBUG or INFO) to aid in development and debugging.

Basic usage

handler.ts:

import { Router } from '@aws-lambda-powertools/event-handler/experimental-rest';
import { Logger } from '@aws-lambda-powertools/logger';
import type { Context } from 'aws-lambda';

const logger = new Logger();
const app = new Router({ logger });

app.get('/todos/:todoId', async ({ todoId }) => {
  const todo = await getTodoById(todoId);
  return { todo };
});

app.post('/todos', async (_, { request }) => {
  const body = await request.json();
  const newTodo = await createTodo(body);
  return { todo: newTodo };
});

export const handler = async (event: unknown, context: Context) => {
  // Set POWERTOOLS_DEV=true to enable request/response logging
  return app.resolve(event, context);
};

Expected log output when POWERTOOLS_DEV=true:

{
  "level": "DEBUG",
  "message": "GET /todos/123 - Incoming request",
  "request": {
    "method": "GET",
    "path": "/todos/123",
    "headers": {
      "content-type": "application/json",
      "x-api-key": "***"
    },
    "queryParams": {},
    "pathParams": {
      "todoId": "123"
    },
    "body": null
  }
}

{
  "level": "DEBUG",
  "message": "GET /todos/123 - Outgoing response",
  "response": {
    "statusCode": 200,
    "headers": {
      "content-type": "application/json"
    },
    "body": {
      "todo": {
        "id": "123",
        "title": "Sample todo"
      }
    }
  }
}

Implementation approach

The logging could be implemented as:

1. Built-in middleware: Automatically applied when debug mode is enabled
2. Router-level logging: Integrated directly into the Router's request processing pipeline

Alternative solutions

Developers can currently implement manual logging by:

1. Adding logging middleware to each route
2. Manually logging in each route handler

However, these approaches require additional setup and don't provide the seamless development experience that built-in debug logging would offer.

Open questions

Should the messages include the - Incoming request and - Outgoing response suffixes?
Should the response just be GET /todos/123 - 200, where 200 is the HTTP status code?
Should we log also the middleware pre-post steps?
Other formats/suggestions?

Acknowledgment

• This feature request meets Powertools for AWS Lambda (TypeScript) Tenets
• Should this be considered in other Powertools for AWS Lambda languages? i.e. Python, Java, and .NET

Future readers

Please react with 👍 and your use case to help us understand customer demand.