All jobs

Add Lambda Powertools to a Serverless Framework Node.js API

Yes. An agent adds Powertools Logger, Tracer and Metrics to your Serverless Framework Lambda, wires them through middy, tests the handler locally 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 clones the service into its own cloud sandbox and reads how the function is defined before adding anything. In a service like aws-node-express-api in serverless/examples, serverless.yml declares frameworkVersion: "4", the aws provider on nodejs24.x and arm64, and one function, api, whose handler is handler.handler and whose single event is httpApi: "*", so every route goes through one Lambda. handler.js builds an Express app with GET / and GET /hello returning JSON, a catch-all that answers 404, and exports serverless(app) from the serverless-http package. package.json has two dependencies, express at ^5.2.1 and serverless-http at ^4.0.0, no dev dependencies, no scripts and no tests. There is no console.log, no tracing setting, no custom metric and no structured log line anywhere, so a failing request in production is a line in CloudWatch with nothing to search by.

It adds @aws-lambda-powertools/logger, @aws-lambda-powertools/tracer and @aws-lambda-powertools/metrics, plus @middy/core to attach them to the handler without touching Express's routes. A new powertools.js constructs one Logger, Tracer and Metrics with the service name from serverless.yml, and handler.js exports middy(serverless(app)).use(injectLambdaContext(logger, { logEvent: false })).use(captureLambdaHandler(tracer)).use(logMetrics(metrics, { captureColdStartMetric: true })). Inside Express, a first middleware appends the request id, method and path to the logger's keys and logs one line per request on finish with the status and elapsed time; the catch-all logs a warning and adds a NotFound count metric. logEvent stays off because the HTTP API event carries headers a log should not keep by default.

In serverless.yml it sets provider.tracing.lambda: true so the function runs with active X-Ray tracing and the Tracer has a segment to annotate, which the Framework turns into the IAM statements the function needs, and adds POWERTOOLS_SERVICE_NAME, POWERTOOLS_LOG_LEVEL and POWERTOOLS_METRICS_NAMESPACE under provider.environment so the values are visible in one place rather than in code. Because Serverless Framework 4 bundles Node functions with esbuild, the agent checks the default build.esbuild settings keep Powertools' optional peer dependencies out of the bundle and adds an external entry only if the bundle fails.

It proves the handler without deploying it. Since package.json has no test tooling, it adds a test script that runs node --test, and a test/handler.test.js that invokes the exported handler with a synthetic HTTP API v2 event and context for /, /hello and an unknown path, captures stdout, and asserts that each run printed one JSON log line with service, cold_start, the path and the status, and that the unknown path emitted the EMF metrics blob with NotFound at 1. The Tracer is set to inactive through its environment variable in the test so no X-Ray daemon is needed. serverless package needs a Serverless Framework login the sandbox does not have, so the pull request says the reviewer runs serverless deploy --stage dev once to see the first traces and logs.

Start it with one API call

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

{
  "agent": "claude",
  "input": "Add AWS Lambda Powertools for TypeScript to this Serverless Framework Node.js service. Read serverless.yml, the handler and package.json first, and say what the function logs and traces today. Add the Powertools logger, tracer and metrics packages and middy, create them once with the service name, wrap the exported handler with the three middlewares without changing the Express routes, log one structured line per request with the request id, method, path, status and duration, count unknown paths as a metric, enable active tracing on the provider, and put the Powertools environment variables under the provider. Keep event logging off. Add a node --test suite that invokes the handler with synthetic HTTP API events and asserts on the JSON log lines and the metrics output with the tracer disabled, run it, and open a pull request with the output and the one deploy command the reviewer should run.",
  "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

What comes back is a pull request changing serverless.yml, handler.js and package.json, and adding powertools.js and test/handler.test.js. The description shows one example log line and one metrics blob exactly as the sandbox test captured them, lists the environment variables and the tracing setting added to the provider, and names the IAM permissions the Framework will add for X-Ray so nobody is surprised by the deploy diff.

The run's record keeps the npm install and the node --test run from the sandbox, so a reviewer sees the handler answer each synthetic event and the assertions on the structured output pass, and can read the test to see which fields are promised.

Before merging, a reviewer runs serverless deploy --stage dev, calls the endpoint and an unknown path once each, and checks CloudWatch Logs for the JSON lines, the metrics namespace for NotFound, and X-Ray for a trace with the handler segment, then decides the log level for production.

Run it on every Serverless Framework service without structured logs

A team with many services hands this off from the terminal once per repository: one POST /o/{org}/sessions with this body and the repository in resources, and a request_id that is a UUID v5 of the repository name so a retried call returns the run it already started. The key's webhook_url reports each finished run with its pull request.

Each run reads that service's own serverless.yml, so a service with several functions gets the middlewares on each handler and one shared powertools.js, and a TypeScript service gets the same change in .ts with the types the packages ship, without the prompt changing.

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

Why run it on Rush?

Powertools is three small packages and a middleware chain, but the value is in the details a reader cannot see from the README: whether the tracer has a segment to write to, whether event logging leaks headers, whether the bundler keeps the optional peers out, and whether the log line carries the fields on-call will search by. The agent reads the real handler and service file in its own sandbox, makes those choices explicitly, and runs the handler against synthetic events to show the exact lines it will emit, before the pull request exists.

The same body runs across every Serverless Framework service a team deploys, and each pull request keeps its own example log line, its own metrics blob and its own test output. That is how a team gets the same observability shape across services written by different people, with the run's record showing what was checked.

Frequently asked questions

Will it change my Express routes?

No. The routes in handler.js stay as they are. Powertools attaches around the exported handler through middy, and the only Express addition is one middleware at the top that annotates the logger and logs the finished request, plus one log and one metric in the existing 404 handler.

Why is event logging off?

Because an HTTP API event includes every request header, which can carry an authorization token or a cookie. injectLambdaContext is called with logEvent: false, and the per-request line carries the method, path, request id and status instead. Turn it on for a debug stage with the POWERTOOLS_LOGGER_LOG_EVENT variable.

Does the tracer need anything deployed besides the code?

Only the setting the pull request adds: provider.tracing.lambda: true in serverless.yml. The Framework adds the X-Ray write permissions to the function's role from that setting, and the Tracer annotates the segment Lambda creates. Without it the Tracer runs but has nothing to write to.

How does the test run without AWS?

The handler is a plain function, so the test builds an HTTP API v2 event and a context object and calls it directly with node --test. The Tracer is disabled through its environment variable, the Logger writes to stdout, and the Metrics middleware prints its EMF blob on flush, so the test captures both and asserts on their fields.

Will the bundle get bigger?

By the three packages and middy, and the pull request names the sizes it saw in node_modules after install. Serverless Framework 4 bundles with esbuild and tree-shakes what the handler does not import; the agent checks the default build settings and adds an external entry only if the bundle step fails on an optional peer.

More Serverless Framework jobs

The same job on other stacks

More jobs like this: Hand off a long task

Keep reading