# 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 Rush](https://cloud.getrush.ai/run/add-lambda-powertools/serverless/). Opens 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`

```json
{
  "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.

## 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

- [Set CloudWatch Log Retention in a Serverless Framework Service](https://getrush.ai/run/add-log-retention/serverless/)
- [Add Rate Limiting to a Serverless Framework API from a Linear Issue](https://getrush.ai/run/add-rate-limiting/serverless/)
- [Add Request ID Logging to a Serverless Express API](https://getrush.ai/run/add-request-id-logging/serverless/)

## The same job on other stacks

- [Add Lambda Powertools to an AWS CDK App from a Linear Issue](https://getrush.ai/run/add-lambda-powertools/aws-cdk/)

## More jobs like this: Hand off a long task

- [Add a Language Switcher to a Wagtail Site](https://getrush.ai/run/add-language-switcher/wagtail/)
- [Show a Last Updated Date from Git History on Eleventy Posts](https://getrush.ai/run/add-last-modified-dates/eleventy/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
