All jobs

Add Request ID Logging to a Serverless Express API

Yes. An agent ties every log line of your Express-on-Lambda API to the API Gateway and Lambda request ids, echoes one in a header, tests it and opens a PR.

Run this on RushOpens the console with this prompt ready to send, in a Project that has your repository.

What the agent does

The agent reads how a request reaches Express before deciding where the id comes from. In a service laid out like aws-node-express-api in serverless/examples, serverless.yml is frameworkVersion "4" on the aws provider with runtime: nodejs24.x and architecture: arm64, and one function, api, whose handler is handler.handler and whose event is httpApi: "*", so every path and method of an API Gateway HTTP API lands in one Lambda. handler.js builds an Express 5 app with GET / and GET /hello answering JSON, a final middleware answering 404 Not Found, and exports.handler = serverless(app) from serverless-http 4. package.json lists only express and serverless-http, with no scripts and no tests. Nothing logs today, so a 404 or a slow call shows in CloudWatch as the platform's own START, END and REPORT lines with the invocation id and nothing from the app to match them to.

There are two ids worth keeping and one worth honouring. API Gateway's HTTP API puts its own request id in event.requestContext.requestId, which is what the gateway's access logs and a 5xx from the gateway itself carry; Lambda puts the invocation id in context.awsRequestId, which is what the REPORT line and the function's CloudWatch stream carry; and a caller may send x-request-id, which should be echoed so a client's logs and the service's logs agree. serverless-http exposes the event and context through its request option, so the agent wraps the app as serverless(app, { request: (req, event, context) => { … } }) and sets req.ids to the gateway id, the invocation id and the caller's header when present, choosing the caller's header as the id to echo and otherwise the gateway's. A small log.js writes one JSON line per call with console.log(JSON.stringify({ level, msg, requestId, awsRequestId, ...fields })), which CloudWatch stores as one event per line and which Logs Insights can filter by field.

The first middleware in handler.js sets res.set('x-request-id', req.ids.requestId) and records performance.now(); a listener on res's finish event logs request_completed with method, path, status and durationMs, so every call, including the 404 fall-through, produces exactly one line carrying both ids. The two route handlers and the 404 handler are otherwise untouched, and a thrown error reaches Express 5's default handler as before, now with the ids in the line the finish listener writes for the 500. The agent does not add a logging library, since the service has no dependencies beyond Express and the adapter and a JSON line to stdout is what Lambda's log pipeline expects, and it does not change the serverless.yml, which has no logging configuration to extend.

Tests come with no test runner in the project, so the agent uses node:test and a test script, which nodejs24.x provides without a dependency. handler.js also exports app, and the first test starts it on an ephemeral port, calls /hello with fetch and an x-request-id header, and asserts the header comes back and that a captured stdout line parses as JSON with the same id, status 200 and a numeric durationMs; the second builds an HTTP API payload version 2.0 event with a requestContext.requestId and a context with awsRequestId and calls the exported handler, asserting the response body and that the logged line carries both ids; the third hits an unknown path and asserts the 404 line. It runs npm test in its sandbox and pastes the output into the pull request. It cannot deploy, because the sandbox has no AWS credentials, and says so; serverless deploy and a curl against the real endpoint are the one step left to the reviewer.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Add request id logging to this Serverless Framework Express API. Read serverless.yml, handler.js, package.json and README.md first. Use serverless-http's request option to read event.requestContext.requestId and context.awsRequestId on each call, honour an incoming x-request-id header as the id to echo and otherwise use the gateway's, and set x-request-id on every response. Write a small log.js that prints one JSON line per call to stdout with level, msg, requestId, awsRequestId and any fields, and add a first middleware that logs request_completed on the response's finish event with method, path, status and durationMs, so every call including the 404 fall-through logs exactly once. Add no logging dependency and do not change serverless.yml. Export the Express app beside the handler and add tests on node:test with a test script: one through the app on an ephemeral port with an x-request-id header, one through the exported handler with an HTTP API 2.0 event and a Lambda context, one for the 404 path, each asserting the header and the parsed log line. Run npm test in your sandbox and open a pull request with the output; say that deploying was not possible without AWS credentials and what the reviewer should curl after serverless deploy.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
  1. Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
  2. Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
  3. Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

What comes back

The pull request adds log.js and test/handler.test.js, changes handler.js to wrap the app with the request option, add the first middleware and export app, and adds a test script to package.json. Its description shows the node --test output for the three tests and three sample log lines from the sandbox run, one with a caller-supplied id, one with the gateway's, one for a 404, each with the awsRequestId beside it.

Nothing changes in what the API answers: the JSON bodies of / and /hello and the 404 body are the same, with one new x-request-id header on every response. serverless.yml is untouched, so the deploy is the same function with the same event, and the one visible difference in CloudWatch is a JSON line per call next to the platform's REPORT line.

Before merging, a reviewer runs serverless deploy to a stage, calls the endpoint with and without x-request-id, and checks in CloudWatch that the awsRequestId in the app's line matches the REPORT line of the same invocation; the pull request lists the exact curl and the Logs Insights query. They also decide whether to turn on API Gateway access logs so the gateway's id appears on both sides.

Run it on every service whose logs cannot be tied to a response

A team with several Serverless Framework services starts one run per repository from its own server: one POST /o/{org}/sessions each, with the repository in resources and a request_id that is a UUID v5 of the repository's full name, so a retried call returns the run already started. Each run reads its own serverless.yml and handler, so a service on the REST API event gets the id from that payload's requestContext, one that already uses a logger gets the ids added as fields of it, and one with several functions gets the same wrapper on each.

Later, a Linear issue labelled observability in the Project can start a run through an automation with a linear trigger and a prompt that names the field the issue asks for; the trigger adds the issue after the prompt, so a request to log the gateway's routeKey or the cold-start flag from the context arrives as a reviewed change with its test.

The use case this job follows, with its automation and trigger: Hand off a long task.

Why run it on Rush?

On Lambda the request id already exists twice, in the gateway's event and in the function's context, and the whole job is to get both into every line the app writes and one of them back to the caller without a dependency the deploy does not need. The agent reads the adapter's option that exposes them, writes the lines and proves them through the real handler signature in its own sandbox, with the event shape the gateway sends, so the first deploy is not the first test.

The transcript keeps the test output and the sample lines, so a reviewer reads what CloudWatch will show before deploying anything. Several services can get the same ids at once, each in its own sandbox, and the one step the sandbox cannot take, the deploy, is written down with the exact check to run after it.

Frequently asked questions

Why log both the gateway id and the Lambda id?

They answer different questions. context.awsRequestId is in the REPORT line and in the function's CloudWatch stream, so it finds the invocation's duration and memory; event.requestContext.requestId is in the gateway's access logs and in a 5xx the gateway answers itself, so it finds a request that never reached the function. The line carries both, and the header echoes the one a client can act on.

Why not pino or winston?

The service has two dependencies and no logger, and Lambda sends stdout to CloudWatch one line at a time, so a JSON.stringify per call is already structured. A library would add package size to every cold start for formatting the runtime already handles; if the team standardises on one later, the log.js call sites are the only lines to change.

How is it tested without deploying?

Two ways. The exported Express app is started on an ephemeral port and called with fetch, which tests the middleware and the header; and the exported handler is called directly with an HTTP API payload version 2.0 event and a context object carrying awsRequestId, which tests the adapter's request option with the shape the gateway sends. Both read the log line back from captured stdout.

Does a caller's x-request-id replace the gateway's id?

It becomes the id that is echoed and logged as requestId, so a client that generated one can find the call by it; the gateway's id and the invocation id are still logged beside it. A header longer than a sane limit or with characters outside a plain token is ignored and the gateway's id is used, which one of the tests covers.

More Serverless Framework jobs

The same job on other stacks

Keep reading