# Add X-Ray Tracing to a Serverless Framework API from a Linear Issue

Yes. An agent turns on Lambda tracing in serverless.yml, instruments the DynamoDB client with the X-Ray SDK, explains the HTTP API limit and opens a pull request.

[Run this on Rush](https://cloud.getrush.ai/run/add-xray-tracing/serverless/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent reads the service definition and the handler before changing either. In a service shaped like `aws-node-express-dynamodb-api` from serverless/examples, `serverless.yml` declares `frameworkVersion: "4"`, a `provider` on `nodejs24.x` and `arm64`, an IAM statement granting `dynamodb:Query`, `Scan`, `GetItem`, `PutItem`, `UpdateItem` and `DeleteItem` on `UsersTable`, an environment variable `USERS_TABLE` set from `${param:tableName}` (`users-table-${sls:stage}`), one function `api` with `handler.handler` on `httpApi: "*"`, and a `PAY_PER_REQUEST` DynamoDB table in `resources`. `handler.js` builds an Express 5 app behind `serverless-http`, creates one `DynamoDBClient` wrapped in `DynamoDBDocumentClient.from(...)`, and serves `GET /users/:userId` and `POST /users` with `GetCommand` and `PutCommand`. `package.json` lists `@aws-sdk/client-dynamodb` and `@aws-sdk/lib-dynamodb` at `^3.585.0`, `express` at `^5.2.1` and `serverless-http` at `^4.0.0`, with no lockfile committed and no tests; `.gitignore` covers `node_modules` and `.serverless`. There is no `tracing` key anywhere in the repository.

The agent adds `tracing: { lambda: true }` under `provider`, which makes the Framework set `TracingConfig: Active` on the function and add the X-Ray write permissions to the generated role. It does not add `tracing: { apiGateway: true }`, because this service uses the `httpApi` event, and API Gateway's HTTP API does not emit X-Ray segments; that setting applies to REST API (`http` events) only. The pull request says so plainly, so nobody waits for gateway segments that cannot appear. If the team wants gateway-level traces they can move to `http` events, which is a separate change with its own costs.

For the function itself, the Lambda runtime opens the segment; what the service lacks is subsegments for its DynamoDB calls. The agent adds `aws-xray-sdk-core` to `dependencies` and wraps the client once at module load with `captureAWSv3Client(new DynamoDBClient())`, so every `GetCommand` and `PutCommand` through `docClient` shows as a subsegment with the table name and the call's status. Outside Lambda the SDK logs a missing-context error, so the agent sets `AWS_XRAY_CONTEXT_MISSING=LOG_ERROR` in the function's `environment` rather than letting a local require fail, and notes that in the sandbox the module loads cleanly with `node -e "require('./handler')"`.

Verification depends on one thing the sandbox may not have. The Framework's v4 CLI signs in with a Serverless access key, so `serverless package` only runs when the Project has `SERVERLESS_ACCESS_KEY` saved as a secret. When it does, the agent runs `npm install`, `serverless package`, and reads `.serverless/cloudformation-template-update-stack.json` to show `TracingConfig` on the function and the X-Ray actions in the role policy, and pastes those lines in the pull request. When it does not, the agent says so, validates the YAML by reading the Framework's documented schema, and leaves the packaged-template check as the first thing a maintainer runs. The `.serverless` directory is already ignored, so nothing generated is committed.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add X-Ray tracing to this Serverless Framework service and open a pull request. Read serverless.yml, handler.js, package.json and .gitignore first. Under provider add tracing with lambda set to true. Do not add apiGateway tracing: this service uses the httpApi event and HTTP API does not produce X-Ray segments, so say that in the pull request instead and name the alternative of REST API http events. Add aws-xray-sdk-core to dependencies and wrap the DynamoDBClient once at module load with captureAWSv3Client so every DynamoDB call becomes a subsegment; set AWS_XRAY_CONTEXT_MISSING to LOG_ERROR in the function environment so the module loads outside Lambda. Run npm install and node -e \"require('./handler')\" to show the handler loads. If SERVERLESS_ACCESS_KEY is present in the environment, run serverless package and paste the TracingConfig block and the X-Ray role statements from .serverless/cloudformation-template-update-stack.json in the pull request description; if it is not present, say so and list that command as the first thing to run. Commit nothing from .serverless or node_modules, and change nothing else.",
  "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 with three changed files: `serverless.yml` with `tracing: lambda: true` and the new environment variable, `package.json` with `aws-xray-sdk-core` added, and `handler.js` with the wrapped client. The description states that HTTP API produces no gateway segments and why the `apiGateway` flag was not set, shows the `node -e` require succeeding, and, when the Project had the Framework access key, quotes the `TracingConfig` and role statements from the packaged template.

A reviewer checks that the client is wrapped exactly once at module scope and not per request, that the function role gained only the X-Ray write actions the Framework adds for `tracing.lambda`, and that no `.serverless` output was committed. After merge, the next `serverless deploy` turns on active tracing, and the first requests to `/users` show a Lambda segment with DynamoDB subsegments in the X-Ray console.

## Run it on every Linear issue labelled agent

In the console, an automation with a `linear` trigger on `linear.issue.labeled` and the label `agent` starts one run per labelled issue, with the issue as its context, in the Project that has the repository. An issue titled `Enable X-Ray on the users API` with this prompt in its description is the whole input, and because the Project holds `SERVERLESS_ACCESS_KEY` as a secret, every run from it can package the service. Changes made by an app integration never fire the trigger, so the agent's own comment on the issue does not start a second run.

From your own server, the same run is one `POST /o/{org}/p/{project}/sessions` per issue, so the secret is in front of the agent: the repository in `resources`, plus the issue's `https://linear.app/<workspace>/issue/<ID>` URL there too, read through your Linear connection into the prompt. A webhook on the API key posts `run.completed` or `run.failed` when the turn finishes, with the `session_url` to read the pull request link.

## Why run it on Rush?

The two lines in `serverless.yml` are easy; knowing which of them does nothing is the work. `apiGateway: true` is in every tutorial and silently has no effect on an `httpApi` service, and a wrapped SDK client that is created per request or without the context-missing setting fails in exactly the environment where nobody looks, local tests. The agent reads the event type, picks the settings that apply, loads the handler in its own sandbox, and packages the service when it has the key, so the pull request carries the generated template's `TracingConfig` as evidence instead of a screenshot of the console.

A Project secret makes that evidence routine. Once `SERVERLESS_ACCESS_KEY` is saved on the Project, every run started in it, from a Linear label or from your server, can run `serverless package` and read the template, and the run's record keeps the output beside the diff.

## Frequently asked questions

### Why no API Gateway traces?

The service's function listens on an `httpApi` event, which is API Gateway's HTTP API, and HTTP API does not integrate with X-Ray. The `tracing.apiGateway` setting only applies to REST API, the `http` event. The agent leaves it out and says so, rather than adding a flag that would do nothing.

### Does it need a Serverless access key?

Only to run `serverless package`, because the v4 CLI signs in. Save it as a Project secret named `SERVERLESS_ACCESS_KEY` and start the run in that Project, and the agent packages the service and quotes the template. Without it, the agent still makes the change and names the command as the first thing to run.

### Will it deploy to AWS?

No. The prompt stops at `serverless package`, which renders the CloudFormation template locally and needs no AWS credentials. Deploying is the maintainers' step after review, and the first deployment is when active tracing takes effect.

### Why wrap the client at module load instead of in each route?

The handler already creates one `DynamoDBClient` at module scope and reuses it across invocations, which is what keeps connections warm. Wrapping that one instance with `captureAWSv3Client` once gives every command a subsegment; wrapping per request would create a client per call and lose the reuse.

## More Serverless Framework jobs

- [Investigate Lambda Timeouts in a Serverless Service](https://getrush.ai/run/investigate-lambda-timeouts/serverless/)
- [Reduce Cold Starts for a NestJS API on Serverless Framework](https://getrush.ai/run/reduce-cold-starts/serverless/)
- [Upgrade the Lambda Runtime in a Serverless Service](https://getrush.ai/run/upgrade-lambda-runtime/serverless/)

## The same job on other stacks

- [Add X-Ray Tracing to an AWS CDK Stack from a Linear Issue](https://getrush.ai/run/add-xray-tracing/aws-cdk/)

## More jobs like this: Turn a Linear label into a PR

- [Fix "[antd: Menu] `children` will be removed in next major version. Please use `items` instead"](https://getrush.ai/run/fix-antd-menu-children-will-be-removed-warning/antd/)
- [Fix "AttributeError: 'array.array' object has no attribute 'tostring'" on Python 3.9 and Later](https://getrush.ai/run/fix-array-tostring-attribute-error/array/)

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