# Add OpenTelemetry Tracing to a Temporal TypeScript Worker

Yes. An agent adds Temporal's OpenTelemetry interceptors to your TypeScript Worker, Client and Workflows so one trace covers a Workflow and its Activities, in a PR.

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

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

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

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

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

- [Encrypt Temporal Workflow Payloads with a Custom Codec](https://getrush.ai/run/add-payload-encryption/temporal/)
- [Expose Temporal Worker Metrics to Prometheus in a TypeScript Project](https://getrush.ai/run/add-prometheus-metrics/temporal/)
- [Set Up Renovate for a Temporal TypeScript Monorepo](https://getrush.ai/run/add-renovate/temporal/)

## The same job on other stacks

- [Add OpenTelemetry Tracing to an Actix Web App](https://getrush.ai/run/add-opentelemetry/actix/)
- [Add OpenTelemetry Tracing to an aiohttp App](https://getrush.ai/run/add-opentelemetry/aiohttp/)
- [Add OpenTelemetry Tracing to an ASP.NET Core API](https://getrush.ai/run/add-opentelemetry/aspnet-core/)

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