All jobs

Expose Temporal Worker Metrics to Prometheus in a TypeScript Project

Yes. An agent installs the Temporal Runtime with a Prometheus exporter in your worker, makes the bind address configurable, tests the endpoint and opens a PR.

Run this on RushOpens the console with this prompt ready to send, in a Project that has your repository.

What the agent does

The agent clones the repository into its own cloud sandbox and reads the worker before it adds telemetry. In a project like temporalio/money-transfer-project-template-ts, package.json pins @temporalio/worker, @temporalio/workflow, @temporalio/activity, @temporalio/client, @temporalio/common and @temporalio/envconfig at ~1.14.1, with @temporalio/testing as a dev dependency; .nvmrc says 18 and tsconfig.json extends @tsconfig/node18. The scripts are worker (ts-node src/worker.ts), client, build (tsc --build) and test (mocha over src/mocha/*.test.ts). src/worker.ts loads connection options with loadClientConnectConfig, opens a NativeConnection, and calls Worker.create with workflowsPath: require.resolve('./workflows'), the activities and the money-transfer task queue from src/shared.ts. Nothing in the file touches Runtime, and a search for telemetryOptions, prometheus and otel across src/ finds nothing.

The workflow and activities tell the agent what the metrics will show. src/workflows.ts proxies withdraw, deposit and refund with a retry policy (initialInterval 1 second, maximumInterval 1 minute, backoffCoefficient 2, maximumAttempts 500, non-retryable InvalidAccountError and InsufficientFundsError) and a one-minute startToCloseTimeout, and compensates a failed deposit with a refund; src/activities.ts calls a mock BankingService in src/banking-client.ts that never makes a network call. The tests in src/mocha/ already use MockActivityEnvironment for activities and TestWorkflowEnvironment.createLocal() with a Worker whose activities are mocked for the workflow.

The change is in src/worker.ts. Before the connection is opened, the agent calls Runtime.install({ telemetryOptions: { metrics: { prometheus: { bindAddress } } } }), with Runtime imported from @temporalio/worker and bindAddress read from TEMPORAL_METRICS_ADDRESS, defaulting to 0.0.0.0:9464. It adds globalTags with a service label so several workers scraped by one Prometheus can be told apart, and a comment that the Runtime is created once per process and must be installed before any NativeConnection or Worker, which is why the call sits first in run(). A short docs/metrics.md shows a scrape_configs entry for the port and names the counters and histograms the SDK publishes, which all start with temporal_, and README.md gets a line pointing to it.

The agent writes src/mocha/metrics.test.ts to prove the endpoint: it installs the Runtime with a bind address on a free loopback port, creates a TestWorkflowEnvironment and a Worker with the mocked activities exactly as workflows.test.ts does, executes moneyTransfer once, then fetches /metrics from that port and asserts the body is Prometheus text with at least one temporal_ series. Because the Runtime is a singleton, the test file installs it in a before hook and the agent checks that the existing suite still passes when the files run together. It runs npm run lint, npm run build and npm test in the sandbox, with a local Temporal dev server started by TestWorkflowEnvironment, and keeps the output.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Add Prometheus metrics to the Temporal worker in this TypeScript project. Read package.json, src/worker.ts, src/workflows.ts and the tests under src/mocha first. In the worker, install the Temporal Runtime with telemetryOptions.metrics.prometheus before any connection or Worker is created, with the bind address read from an environment variable and a sensible default, and add a global service tag. Write a mocha test that installs the Runtime on a free port, runs one workflow against a TestWorkflowEnvironment with mocked activities, and asserts that the metrics endpoint returns Prometheus text containing Temporal series. Add a short doc with a scrape config. Run lint, build and the full test suite, and open a pull request that shows a sample of the metrics output. Change nothing in the workflow or activity code.",
  "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 edits src/worker.ts and README.md and adds src/mocha/metrics.test.ts and docs/metrics.md. The description shows the first lines of the /metrics response captured in the test, explains the environment variable and its default, quotes the npm test output with the existing and new tests, and states that src/workflows.ts and src/activities.ts are untouched.

The run's record keeps the commands and their output, including the TestWorkflowEnvironment download of the dev server and the test run, so a reviewer can see the endpoint answered in the sandbox rather than take the description's word for it.

Before merging, a reviewer decides the port and whether the worker's container or pod exposes it, checks the service tag value against the naming the team's dashboards use, and considers whether the client in src/client.ts should also emit metrics, which is a separate change.

Run it on every new worker

In the console, an automation in the Project that has the repository, with a github trigger on pull_request.opened and pull_request.synchronize and branch_patterns for your default branch, starts one run per pull request, with the pull request as its context; its prompt asks the run to add the same Runtime setup on the pull request's branch when the pull request adds a file calling Worker.create, and to stop otherwise.

From your own server, the same work is one POST /o/{org}/sessions per worker repository with this body and the repository in resources, and a webhook on the API key reports run.completed with the session_url to read the pull request link.

The use case this job follows, with its automation and trigger: Hand off a long task.

Why run it on Rush?

The Runtime setup is a few lines, but it has an ordering rule (install before any connection) and a testing wrinkle (one Runtime per process) that are easy to get wrong in a project with an existing test suite. The agent reads the worker and the tests first, places the call where it has to be, and proves the endpoint in a test that runs beside the existing ones.

The proof is real output: the sandbox starts a Temporal dev server through the testing package, runs a workflow, scrapes the port and keeps the response in the record. Several worker services can get the same change at the same time in separate sandboxes.

Frequently asked questions

Does this change workflow or activity code?

No. Metrics come from the SDK's Runtime, so only src/worker.ts changes, plus the new test and doc. The prompt forbids touching src/workflows.ts and src/activities.ts, and the diff shows it.

Can it export to an OpenTelemetry collector instead?

Yes. The same telemetryOptions.metrics block takes an otel entry with the collector's URL in place of prometheus. Say which in input and the agent writes that form, with the test adjusted to check the exporter was configured rather than scraping a port.

Why does the Runtime have to be installed first?

The Temporal Runtime is created once per process the first time a connection or Worker needs it, with default options. A Runtime.install after that point throws, so the call must come before NativeConnection.connect, which is where the agent puts it.

Will the existing mocha tests still pass?

The agent runs the whole suite together, since the new test installs a Runtime that the existing TestWorkflowEnvironment tests then share. The npm test output in the pull request shows all files passing in one process.

More Temporal jobs

The same job on other stacks

Keep reading