What the agent does
The agent reads the Worker, the Client and the Workflow before adding anything. In a project like temporalio/money-transfer-project-template-ts, package.json pins every @temporalio/* package at ~1.14.1 and .nvmrc says Node 18, with tsconfig.json extending @tsconfig/node18. src/worker.ts connects with NativeConnection, calls Worker.create with workflowsPath: require.resolve('./workflows'), the activities module and the money-transfer task queue from src/shared.ts, and src/client.ts starts moneyTransfer with a fixed workflowId. src/workflows.ts proxies withdraw, deposit and refund with a retry policy of up to 500 attempts and two non-retryable error types, and .eslintrc.js forbids Node built-in imports in that file, which is the constraint any tracing code inside a Workflow has to respect.
It picks the tracing package that matches the pinned SDK line: @temporalio/interceptors-opentelemetry at ~1.14.1, whose peer dependency is @temporalio/common at the same version, rather than the newer plugin-style package that belongs to a later SDK. Alongside it come @opentelemetry/sdk-trace-node, @opentelemetry/sdk-trace-base, @opentelemetry/resources, @opentelemetry/semantic-conventions and @opentelemetry/exporter-trace-otlp-grpc. A new src/instrumentation.ts builds a Resource with a service.name, a span exporter that is OTLP over gRPC when OTEL_EXPORTER_OTLP_ENDPOINT is set and a console exporter otherwise, and a batch span processor on a Node tracer provider, so the same code runs in a laptop shell and in a cluster with a collector.
Then the three sides are wired. src/workflows.ts gains an exported interceptors function returning OpenTelemetryInboundInterceptor, OpenTelemetryOutboundInterceptor and OpenTelemetryInternalsInterceptor instances, which is how Workflow code, running in its isolated sandbox without Node modules, records spans and hands them to the Worker. src/worker.ts passes sinks: makeWorkflowExporter(exporter, resource) so those spans are exported outside the sandbox, and interceptors: { workflowModules: [require.resolve('./workflows')], activity: [(ctx) => ({ inbound: new OpenTelemetryActivityInboundInterceptor(ctx) })] } so each Activity run becomes a child span. src/client.ts gets interceptors: { workflow: [new OpenTelemetryWorkflowClientInterceptor()] } so the trace begins where the Workflow is started and its context travels in the Workflow headers. The result is one trace with a RunWorkflow:moneyTransfer span and StartActivity and RunActivity children for withdraw and deposit.
The checks are the repository's own. npm run lint must still pass, including the no-restricted-imports rule on src/workflows.ts, and npm test runs the Mocha suite in src/mocha/, where TestWorkflowEnvironment.createLocal() starts a local test server and the Workflow test registers its own Worker.create with mock Activities, so the agent adds the same sinks and interceptors there and shows the spans the console exporter prints during the test. npm run build with tsc --build confirms the types, and the README gains the two environment variables that point the exporter at a collector.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add OpenTelemetry tracing to this Temporal TypeScript project. Read package.json, .nvmrc, tsconfig.json, .eslintrc.js, src/worker.ts, src/client.ts, src/workflows.ts, src/activities.ts, src/shared.ts and the Mocha tests first. Add @temporalio/interceptors-opentelemetry at the same version range as the other @temporalio packages, plus the OpenTelemetry SDK, resources, semantic-conventions and OTLP gRPC trace exporter packages. Write src/instrumentation.ts with a service.name resource, a batch span processor and an exporter that is OTLP when OTEL_EXPORTER_OTLP_ENDPOINT is set and console otherwise. Export an interceptors function from src/workflows.ts with the inbound, outbound and internals OpenTelemetry interceptors; give the Worker the makeWorkflowExporter sink and the Activity inbound interceptor with workflowModules; give the Client the workflow client interceptor. Wire the same sink and interceptors into the Worker the Mocha workflow test creates. Run npm run lint, npm run build and npm test, show the spans the console exporter prints for one Workflow, document the environment variables in the README, and open a pull request. Do not change the retry policy or the Activities.",
"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 with a new src/instrumentation.ts, the interceptors export in src/workflows.ts, the sinks and interceptors options in src/worker.ts, the client interceptor in src/client.ts, the same wiring in src/mocha/workflows.test.ts, the dependency changes in package.json and package-lock.json, and a README section. src/activities.ts, src/banking-client.ts and the retry policy are untouched.
The description pastes the spans the console exporter printed for one test Workflow, so a reviewer sees the parent and child span names and the shared trace id without running anything, and quotes the lint, build and test results. Every command and its output is in the transcript at GET /o/{org}/sessions/{id}/messages.
Before merging, a reviewer sets OTEL_EXPORTER_OTLP_ENDPOINT against a collector they have, runs npm run worker and npm run client once, and checks the trace arrives with the Workflow id on it. A follow-up message to the same session can add the native runtime metrics through Runtime.install and its telemetryOptions if the team wants Worker metrics beside the traces.
Run it on every Linear issue labelled observability
A platform team that files observability work in Linear starts one run per issue from an automation with a linear trigger on the observability label. The automation adds the issue after this prompt, so an issue that names the collector endpoint or asks for metrics as well is what the agent reads, and the run starts in the repository the automation names.
Each run opens its own pull request from its own sandbox, and an automation run has its own max_runs_per_hour cap. The pull request links the issue and carries the printed spans, so the review is a read of three wiring points and one trace.
The use case this job follows, with its automation and trigger: Turn a Linear label into a PR.
Why run it on Rush?
Tracing a Temporal application touches three processes that must agree on versions and on how context crosses the Workflow sandbox boundary, and the SDK's own lint rule exists because getting that boundary wrong is easy. The agent reads the pinned versions, picks the package that matches them, wires each side the way the interceptor package expects, and proves it by running the repository's Mocha suite against a local test server in its own sandbox.
The pull request carries the spans as printed, with the trace id that ties them together, beside the lint, build and test output. Several Workers can be instrumented at once, each in its own sandbox, with one pull request each.
Frequently asked questions
Why not the newer plugin-based OpenTelemetry package?
This project pins @temporalio/* at ~1.14.1, and @temporalio/interceptors-opentelemetry at the same version is the package built for that line, with @temporalio/common as its peer dependency. The plugin-style package belongs to a later SDK and would mean upgrading every Temporal package first, which is a different change. The pull request names that upgrade as a follow-up.
Can Workflow code import the OpenTelemetry SDK directly?
No, and .eslintrc.js enforces part of that with its no-restricted-imports rule for src/workflows.ts. Workflow code runs in an isolated sandbox without Node modules, so spans recorded there are passed to the Worker through the makeWorkflowExporter sink, and only the Worker process holds the exporter.
Does this change how Activities retry or fail?
No. The retry policy in src/workflows.ts and the nonRetryableErrorTypes list are not touched, and src/activities.ts is unchanged. The Activity inbound interceptor wraps each attempt in a span; a retried attempt shows up as another RunActivity span under the same parent, which is useful rather than disruptive.
Do the existing tests still pass?
The agent runs npm test, which starts a local test server through TestWorkflowEnvironment.createLocal(), and adds the same sink and interceptors to the Worker that test creates. Without that the test Worker would run the Workflow interceptors with no sink to export to; with it, the console exporter prints the spans during the run, which is the output pasted into the pull request.
Where do the traces go?
To whatever OTEL_EXPORTER_OTLP_ENDPOINT names, over OTLP gRPC, and to the console when it is unset. The README section the agent writes lists that variable and OTEL_SERVICE_NAME, and the collector or vendor behind the endpoint is the team's choice.
More Temporal jobs
The same job on other stacks
- Add OpenTelemetry Tracing to an Actix Web App (Actix Web)
- Add OpenTelemetry Tracing to an aiohttp App (aiohttp)
- Add OpenTelemetry Tracing to an ASP.NET Core API (ASP.NET Core)