feat(event-handler): add tracer middleware for HTTP routes (#4982)

Co-authored-by: Andrea Amorosi <dreamorosi@gmail.com>
Co-authored-by: Stefano Vozza <svozza@amazon.com>

Author: 3 people

docs/features/event-handler/http.md

@@ -564,6 +564,53 @@ You can enable response compression by using the `compress` middleware. This wil
     --8<-- "examples/snippets/event-handler/http/samples/advanced_compress_res.json"
     ```
 
+### Tracer
+
+You can enable distributed tracing for your HTTP routes by using the `tracer`. This middleware integrates with [AWS X-Ray](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray.html){target="_blank"} through the [Tracer utility](../tracer.md) to automatically trace each route invocation.
+
+!!! note "Installation"
+    The `tracer` requires the `@aws-lambda-powertools/tracer` package as a peer dependency. Install it separately:
+
+    ```shell
+    npm install @aws-lambda-powertools/tracer
+    ```
+
+The middleware automatically:
+
+* Creates a subsegment for each HTTP route with the format `METHOD /path` (e.g., `GET /users`)
+* Adds `ColdStart` annotation to easily filter cold start traces
+* Adds `Service` annotation for filtering by service name
+* Captures JSON response bodies as metadata (configurable)
+* Captures errors as metadata when exceptions occur
+
+!!! note "Response capture behavior"
+    Only JSON responses are captured as metadata.
+
+=== "index.ts"
+
+    ```ts hl_lines="2 3 6 10"
+    --8<-- "examples/snippets/event-handler/http/advanced_mw_tracer.ts"
+    ```
+
+    ```json hl_lines="11 18-25"
+    --8<-- "examples/snippets/event-handler/http/advanced_mw_tracer.json"
+    ```
+
+#### Disabling response capture
+
+For routes that return sensitive data, you can disable response capture by setting `captureResponse: false`:
+
+=== "index.ts"
+
+    ```ts hl_lines="2 3 6 11"
+    --8<-- "examples/snippets/event-handler/http/advanced_mw_tracer_per_route.ts"
+    ```
+
+#### Streaming limitation
+
+!!! warning "Tracer middleware is disabled for streaming responses"
+    When using HTTP response streaming, the Tracer middleware is automatically disabled to prevent buffering the entire response. In streaming mode the middleware exits early and does not create a subsegment. You can still use the Tracer utility manually within your route handler to create subsegments and add annotations.
+
 ### Binary responses
 
 If you need to return binary data, there are several ways you can do so based on how much control you require.

examples/snippets/event-handler/http/advanced_mw_tracer.json

@@ -0,0 +1,28 @@
+{
+  "subsegments": [
+    {
+      "id": "96706b172edc5427",
+      "name": "Overhead",
+      "start_time": 1769780291.4940002,
+      "end_time": 1769780291.5135612
+    },
+    {
+      "id": "fe5efd6965d43f13",
+      "name": "GET /user",
+      "start_time": 1769780291.434,
+      "end_time": 1769780291.473,
+      "annotations": {
+        "ColdStart": false,
+        "Service": "my-api"
+      },
+      "metadata": {
+        "my-api": {
+          "GET /user response": {
+            "name": "John Doe",
+            "id": "1dd62759-f47f-4382-93c3-4c0282d13e08"
+          }
+        }
+      }
+    }
+  ]
+}

examples/snippets/event-handler/http/advanced_mw_tracer.ts

@@ -0,0 +1,21 @@
+import { Router } from '@aws-lambda-powertools/event-handler/http';
+import { tracer as tracerMiddleware } from '@aws-lambda-powertools/event-handler/http/middleware/tracer';
+import { Tracer } from '@aws-lambda-powertools/tracer';
+import type { Context } from 'aws-lambda';
+
+const tracer = new Tracer({ serviceName: 'my-api' });
+const app = new Router();
+
+// Apply globally
+app.use(tracerMiddleware(tracer));
+
+app.get('/users', () => {
+  return { users: [{ id: '1', name: 'John' }] };
+});
+
+app.get('/users/:id', ({ params }) => {
+  return { id: params.id, name: 'John' };
+});
+
+export const handler = async (event: unknown, context: Context) =>
+  app.resolve(event, context);

examples/snippets/event-handler/http/advanced_mw_tracer_per_route.ts

@@ -0,0 +1,18 @@
+import { Router } from '@aws-lambda-powertools/event-handler/http';
+import { tracer as tracerMiddleware } from '@aws-lambda-powertools/event-handler/http/middleware/tracer';
+import { Tracer } from '@aws-lambda-powertools/tracer';
+import type { Context } from 'aws-lambda';
+
+const tracer = new Tracer({ serviceName: 'my-api' });
+const app = new Router();
+
+app.get(
+  '/users/cards',
+  [tracerMiddleware(tracer, { captureResponse: false })],
+  ({ params }) => {
+    return { id: params.id, secret: 'sensitive-data' };
+  }
+);
+
+export const handler = async (event: unknown, context: Context) =>
+  app.resolve(event, context);

packages/event-handler/package.json

@@ -89,6 +89,16 @@
         "types": "./lib/esm/http/middleware/index.d.ts",
         "default": "./lib/esm/http/middleware/index.js"
       }
+    },
+    "./http/middleware/tracer": {
+      "require": {
+        "types": "./lib/cjs/http/middleware/tracer.d.ts",
+        "default": "./lib/cjs/http/middleware/tracer.js"
+      },
+      "import": {
+        "types": "./lib/esm/http/middleware/tracer.d.ts",
+        "default": "./lib/esm/http/middleware/tracer.js"
+      }
     }
   },
   "typesVersions": {
@@ -116,6 +126,10 @@
       "http/middleware": [
         "./lib/cjs/http/middleware/index.d.ts",
         "./lib/esm/http/middleware/index.d.ts"
+      ],
+      "http/middleware/tracer": [
+        "./lib/cjs/http/middleware/tracer.d.ts",
+        "./lib/esm/http/middleware/tracer.d.ts"
       ]
     }
   },
@@ -132,6 +146,14 @@
   "dependencies": {
     "@aws-lambda-powertools/commons": "2.30.2"
   },
+  "peerDependencies": {
+    "@aws-lambda-powertools/tracer": ">=2.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@aws-lambda-powertools/tracer": {
+      "optional": true
+    }
+  },
   "keywords": [
     "aws",
     "lambda",

packages/event-handler/src/http/Router.ts

@@ -276,6 +276,7 @@ class Router {
       }),
       params: {},
       responseType,
+      isHttpStreaming: options?.isHttpStreaming,
     };
 
     try {

packages/event-handler/src/http/middleware/index.ts

@@ -1,2 +1,3 @@
 export { compress } from './compress.js';
 export { cors } from './cors.js';
+export { tracer } from './tracer.js';

packages/event-handler/src/http/middleware/tracer.ts

@@ -0,0 +1,96 @@
+import type { Tracer } from '@aws-lambda-powertools/tracer';
+import type { Subsegment } from 'aws-xray-sdk-core';
+import type { Middleware, TracerOptions } from '../../types/http.js';
+
+/**
+ * A middleware for tracing HTTP routes using AWS X-Ray.
+ *
+ * This middleware automatically:
+ * - Creates a subsegment for each HTTP route
+ * - Adds `ColdStart` annotation
+ * - Adds service name annotation
+ * - Captures the response as metadata (for non-streaming JSON responses)
+ * - Captures errors as metadata
+ *
+ * **Note:** This middleware is completely disabled when the request is in HTTP streaming mode.
+ *
+ * @example
+ * ```typescript
+ * import { Router } from '@aws-lambda-powertools/event-handler/http';
+ * import { tracer as tracerMiddleware } from '@aws-lambda-powertools/event-handler/http/middleware/tracer';
+ * import { Tracer } from '@aws-lambda-powertools/tracer';
+ *
+ * const tracer = new Tracer({ serviceName: 'my-service' });
+ * const app = new Router();
+ *
+ * // Apply globally
+ * app.use(tracerMiddleware(tracer));
+ *
+ * // Or apply per-route
+ * app.get('/users', [tracerMiddleware(tracer)], async ({ reqCtx }) => {
+ *   return { users: [] };
+ * });
+ * ```
+ *
+ * @param tracer - The Tracer instance to use for tracing
+ * @param options - Optional configuration for the middleware
+ */
+const tracer = (tracer: Tracer, options?: TracerOptions): Middleware => {
+  const {
+    captureResponse = true,
+    logger = {
+      warn: console.warn,
+    },
+  } = options ?? {};
+
+  return async ({ reqCtx, next }) => {
+    if (!tracer.isTracingEnabled() || reqCtx.isHttpStreaming) {
+      await next();
+      return;
+    }
+
+    const url = new URL(reqCtx.req.url);
+    const segmentName = `${reqCtx.req.method} ${url.pathname}`;
+
+    const segment = tracer.getSegment();
+    let subSegment: Subsegment | undefined;
+
+    if (segment) {
+      subSegment = segment.addNewSubsegment(segmentName);
+      tracer.setSegment(subSegment);
+    }
+
+    tracer.annotateColdStart();
+    tracer.addServiceNameAnnotation();
+
+    try {
+      await next();
+
+      if (
+        captureResponse &&
+        reqCtx.res.headers.get('Content-Type') === 'application/json'
+      ) {
+        const responseBody = await reqCtx.res.clone().json();
+        tracer.addResponseAsMetadata(responseBody, segmentName);
+      }
+    } catch (err) {
+      tracer.addErrorAsMetadata(err as Error);
+      throw err;
+    } finally {
+      if (segment && subSegment) {
+        try {
+          subSegment.close();
+        } catch (error) {
+          logger.warn(
+            'Failed to close or serialize segment %s. Data might be lost.',
+            subSegment.name,
+            error
+          );
+        }
+        tracer.setSegment(segment);
+      }
+    }
+  };
+};
+
+export { tracer };

packages/event-handler/src/types/http.ts

@@ -32,6 +32,7 @@ type RequestContext = {
   params: Record<string, string>;
   responseType: ResponseType;
   isBase64Encoded?: boolean;
+  isHttpStreaming?: boolean;
 };
 
 type HttpResolveOptions = ResolveOptions & { isHttpStreaming?: boolean };
@@ -244,6 +245,23 @@ type CompressionOptions = {
   threshold?: number;
 };
 
+/**
+ * Configuration options for Tracer middleware
+ */
+type TracerOptions = {
+  /**
+   * Whether to capture the response body as metadata.
+   * @default true
+   */
+  captureResponse?: boolean;
+  /**
+   * A logger instance to be used for logging.
+   *
+   * When no logger is provided, we'll only log using the global `console` object.
+   */
+  logger?: GenericLogger;
+};
+
 type WebResponseToProxyResultOptions = {
   isBase64Encoded?: boolean;
 };
@@ -281,6 +299,7 @@ export type {
   HttpRouteHandlerOptions,
   RouteRegistryOptions,
   RouterResponse,
+  TracerOptions,
   ValidationResult,
   CompressionOptions,
   NextFunction,

packages/event-handler/src/types/index.ts

@@ -45,4 +45,5 @@ export type {
   Path,
   RequestContext,
   RouteHandler,
+  TracerOptions,
 } from './http.js';