# Add X-Ray Tracing to an AWS CDK Stack from a Linear Issue

Yes. An agent reads the issue, turns on active tracing for your CDK Lambda functions and API stage, instruments the SDK clients, asserts it in Jest and opens a PR.

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

## What the agent does

The agent starts from the Linear issue and the repository in its own sandbox and reads the stack before it changes a construct. In a stack shaped like `api-cors-lambda-crud-dynamodb` in aws-samples/aws-cdk-examples, `index.ts` defines `ApiLambdaCrudDynamoDBStack` on `aws-cdk-lib` 2.262.1 with a `Table` named `items`, five `NodejsFunction` constructs built from `lambdas/create.ts`, `get-all.ts`, `get-one.ts`, `update-one.ts` and `delete-one.ts` on `Runtime.NODEJS_24_X`, sharing a `nodeJsFunctionProps` object that marks `@aws-sdk/*` as external in `bundling` and passes `TABLE_NAME` and `PRIMARY_KEY` in `environment`. A `RestApi` called `Items Service` wires them through `LambdaIntegration`, and `addCorsOptions` adds a mock `OPTIONS` method to each resource. Nothing sets `tracing`, and the `RestApi` has no `deployOptions`, so neither the functions nor the stage sends segments to X-Ray.

Each handler in `lambdas/` builds its own client with `DynamoDBDocument.from(new DynamoDB())` from `@aws-sdk/lib-dynamodb` and `@aws-sdk/client-dynamodb`, pinned in `lambdas/package.json` at `^3.538.0`. `cdk.json` runs the app with `npx tsc && npx tsx index.ts`, and `jest.config.js` is already there with `@swc/jest` and the `aws-cdk-lib/testhelpers/jest-autoclean` setup file, though the example ships no test file. The same repository's `ddb-stream-lambda-sns` stack already sets `tracing: lambda.Tracing.ACTIVE`, which the agent cites as the house style.

The agent adds `tracing: Tracing.ACTIVE` to the shared `nodeJsFunctionProps`, which makes CDK attach the X-Ray write permissions to each function's role, and gives the `RestApi` a `deployOptions` block with `tracingEnabled: true` so the API Gateway stage opens the trace that the functions continue. In the handlers it wraps the client with `captureAWSv3Client` from `aws-xray-sdk-core`, added to `lambdas/package.json`, so each DynamoDB call becomes a subsegment with its table name and latency; the bundling `externalModules` list is left as it is, since the SDK package itself is bundled.

Then it writes `index.test.ts` with `Template.fromStack` assertions: every `AWS::Lambda::Function` has `TracingConfig: { Mode: 'Active' }`, the `AWS::ApiGateway::Stage` has `TracingEnabled: true`, and each function's role policy carries an `xray:PutTraceSegments` and `xray:PutTelemetryRecords` statement, which CDK adds when tracing is active. It runs `npm run build`, `npx jest` and `npx cdk synth`, reads the synthesized template for the same properties, and opens a pull request that links the issue.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "A Linear issue labeled agent says: \"Turn on X-Ray tracing for the items API so we can see API Gateway, Lambda and DynamoDB latency in one trace.\" Do the work in this repository: set tracing to Active on every Lambda function in the stack, enable tracing on the REST API stage through deployOptions, instrument the DynamoDB clients in the handlers with aws-xray-sdk-core so each call is a subsegment, add a Jest test that asserts the TracingConfig, the stage's TracingEnabled flag and the X-Ray permissions in the synthesized template, run the build, the tests and cdk synth, and open a pull request that links back to the issue.",
  "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 on its own branch that links the Linear issue. The diff adds `tracing: Tracing.ACTIVE` to the shared function props and `deployOptions: { tracingEnabled: true }` to the `RestApi` in `index.ts`, wraps the DynamoDB client in each handler under `lambdas/`, adds `aws-xray-sdk-core` to `lambdas/package.json` with its lockfile change, and adds `index.test.ts`. The description names the resources that gained a tracing property in the template.

The run's record keeps `npm run build`, the `jest` run with the new assertions, and `cdk synth` with the template lines showing `TracingConfig`, `TracingEnabled` and the `xray:PutTraceSegments` statement in each role's policy. No deploy happens: the run has no AWS credentials, and the synthesized template is the proof.

Before merging, a reviewer checks that active tracing is wanted on every function rather than only the API path, since each traced invocation is billed by X-Ray, and that the sampling rule the account uses matches the traffic volume. Deploying the stack and opening the service map is the reviewer's step.

## 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. Changes made by an app integration never fire it, so the agent's own updates do not start new runs.

From your own server, the same run is one `POST /o/{org}/sessions` per issue: 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?

Tracing is a property of the synthesized template, and `cdk synth` with a Jest assertion is the honest check that it reached every function and the stage. The sandbox has Node, the CDK CLI and a clean install, so the run synthesizes the stack and keeps the template, with no AWS account in the loop.

A labelled issue becomes a pull request with the construct changes, the handler instrumentation and a test that stops the setting from being dropped later. The same prompt runs against many stacks at once, one sandbox each, and each pull request carries its own synth output.

## Frequently asked questions

### Does the run deploy anything?

No. It builds, tests and synthesizes. The template it reads is the one `cdk deploy` would send, and the pull request shows the tracing properties in it. Deploying stays with you.

### Why instrument the SDK client if the function is already traced?

Active tracing on the function records the invocation as one segment. Wrapping the client adds a subsegment per DynamoDB call with the table and the time it took, which is what lets the trace show whether latency sits in the function or in the table.

### Will the bundle grow?

The X-Ray SDK is bundled into each function by `NodejsFunction`, since it is not in the `externalModules` list. The agent reports the asset size from `cdk synth` in the pull request so the reviewer can see the difference.

### Can it use Powertools for AWS Lambda instead?

Yes. If the repository already depends on `@aws-lambda-powertools/tracer`, the agent uses its `Tracer` and `captureAWSv3Client` rather than adding a second SDK, and says so in the pull request.

## More AWS CDK jobs

- [Fix AWS CDK Errors from Sentry Alerts](https://getrush.ai/run/fix-sentry-errors/aws-cdk/)
- [Protect a DynamoDB Global Table and Its KMS Keys from Deletion in an AWS CDK App](https://getrush.ai/run/protect-stateful-resources/aws-cdk/)
- [Review AWS CDK Pull Requests](https://getrush.ai/run/review-cdk-changes/aws-cdk/)

## The same job on other stacks

- [Add X-Ray Tracing to a Serverless Framework API from a Linear Issue](https://getrush.ai/run/add-xray-tracing/serverless/)

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