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 with this body:
{
"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"
}
]
}- 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.
- 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.
- 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.
The use case this job follows, with its automation and trigger: Turn a Linear label into a PR.
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
The same job on other stacks
- Add X-Ray Tracing to a Serverless Framework API from a Linear Issue (Serverless Framework)