# Add OpenTelemetry Tracing to a Medusa Backend

Yes. The agent completes the backend's instrumentation.ts with registerOtel and an exporter, traces HTTP, workflows, queries and the database, and opens a PR.

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

## What the agent does

The agent reads how the backend is built before it enables anything, because Medusa ships the hook for tracing and the job is choosing what to plug into it. In a store built from medusajs/dtc-starter, the root `package.json` is a pnpm workspace on `pnpm@10.11.1` and Node 22.23.4 or later, with `turbo` running `build`, `lint` and `test` across `apps/backend` and `apps/storefront`. The backend's `package.json` depends on `@medusajs/medusa`, `@medusajs/framework` and `@medusajs/cli` at 2.22.2, builds with `medusa build`, starts with `medusa start` and lints with `medusa lint` through the root `eslint.config.ts`, which loads `@medusajs/eslint-plugin`'s recommended rules. `medusa-config.ts` sets only `databaseUrl`, the three CORS lists and the two secrets from `.env`, so there is no module or plugin block to disturb.

`apps/backend/instrumentation.ts` already exists and is entirely commented out. It shows the shape Medusa expects: import `registerOtel` from `@medusajs/medusa`, build an exporter, and export a `register()` function that calls `registerOtel` with a `serviceName`, the `exporter` and an `instrument` object. Medusa's own instrumentation page, which the file links to, adds that `instrument` takes `http`, `workflows`, `query`, `db` and `cache`, that since 2.22.0 `http` may be an object whose `allowedQueryParams` says which query parameter values are reported with the rest shown as `REDACTED`, and that `registerOtel` also accepts any OpenTelemetry `NodeSDKConfiguration` property. Since 2.11.0 the SDK packages come with a new project, and only the exporter has to be added.

The agent uncomments and completes the file for the backend you name in the prompt. It installs the exporter package for your collector in `apps/backend` with pnpm, so the workspace lockfile changes in one place; the commented example uses `@opentelemetry/exporter-zipkin`, and an OTLP collector takes the matching exporter package instead. `serviceName` becomes the store's name rather than the sample's `medusajs`, the endpoint comes from an environment variable with a line added to `.env.template` beside `REDIS_URL`, and `instrument` enables `http`, `workflows`, `query` and `db`, with `allowedQueryParams` listing the few parameters a store reads such as `limit`, `offset` and `handle`, since a cart or checkout URL can carry a token. It leaves `cache` off until the store configures a cache module, and says so.

Then it proves the file loads. `medusa start` imports the built `instrumentation.js` from the project root and calls `register`, ignoring only a missing file, so a typo there fails startup rather than tracing silently. The agent runs `pnpm install`, `pnpm --filter @dtc/backend build`, `pnpm --filter @dtc/backend lint` and the backend's `test:unit` script, which runs Jest with `@swc/jest` over `src/**/__tests__/**/*.unit.spec.ts`. With a Postgres started in the sandbox and `DATABASE_URL` set, it starts the backend once, requests `/store/custom` and the `/store/search` route behind `src/api/middlewares.ts`, and checks the exporter's output or the collector's log for a span before it opens the pull request.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add OpenTelemetry tracing to the Medusa backend in apps/backend. Read the root package.json, turbo.json, apps/backend/package.json, apps/backend/medusa-config.ts, apps/backend/instrumentation.ts and .env.template first, and read Medusa's instrumentation docs for the installed version. Complete instrumentation.ts: import registerOtel from @medusajs/medusa, build an exporter for an OTLP collector whose endpoint comes from an environment variable (add it to .env.template), set serviceName to the store's name, and enable http, workflows, query and db in instrument, with http.allowedQueryParams limited to limit, offset and handle. Install only the exporter package, in apps/backend with pnpm. Run pnpm install, the backend build, lint and unit tests, then start the backend against a local Postgres and confirm a span is exported for a request to /store/custom. Open a pull request that shows the span and the commands you ran. Change nothing in the storefront.",
  "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 four kinds of change: a completed `apps/backend/instrumentation.ts`, one new dependency in `apps/backend/package.json` and the matching `pnpm-lock.yaml` entries, a new variable in `apps/backend/.env.template`, and a short section in the backend README on where traces go. The description quotes the span the agent saw for its test request, with the service name and the HTTP, query and database child spans under it, and lists the build, lint and test commands with their output.

The session keeps the record: the docs page it read, every `pnpm` command with its full output, the backend's startup log showing `instrumentation.js` loaded, and the request it sent. `GET /o/{org}/sessions/{id}/messages` returns that transcript, and `GET /o/{org}/p/{project}/sessions/{id}/changes` returns the diff per file.

Before merging, a reviewer checks that `allowedQueryParams` lists nothing that could carry a secret, that the endpoint variable is set in each deployment's environment before the branch ships, and that the storefront is untouched. A follow-up message to the same session, such as switching the exporter to the one your vendor documents, continues on the same branch.

## Run it on every backend without traces

Start it from your terminal with one `POST /o/{org}/sessions`, this prompt as `input` and the repository in `resources`, and pick the pull request up from the console when it is ready. The sandbox parks when the turn ends, so a follow-up to the same session wakes it with the dependencies already installed. A `request_id` that is a UUID v5 of the repository's full name makes a retried request return the run already started.

An agency that runs a Medusa backend per client sends the same body once per repository from its own server, each with its own repository in `resources`, and the key's `webhook_url` receives one `run.completed` per backend with the pull request in `result`. Each run reads its own `instrumentation.ts`, so a backend that already exports to one collector gets nothing but a review comment saying so.

## Why run it on Rush?

Enabling tracing by hand is ten minutes of editing and an hour of wondering whether the file loaded, because a backend that fails to register its SDK keeps serving requests and simply emits nothing. In a Rush sandbox the agent installs the workspace with pnpm, starts a Postgres, boots the backend and reads the exporter's output, so the pull request says a span was seen rather than that one should be.

The pull request carries its proof: the span, the startup log and every command's output, kept with the session. Several backends can be instrumented at the same time in separate sandboxes, each against its own `medusa-config.ts` and lockfile, and nothing runs on a laptop.

## Frequently asked questions

### Which exporter does it use?

The one you name in the prompt. The sample file shows Zipkin; an OTLP collector takes the OTLP exporter package instead, and the endpoint always comes from an environment variable so staging and production can differ. `registerOtel` accepts any `NodeSDKConfiguration` property, so a vendor that needs headers gets them the same way.

### Does it need Medusa 2.11 or newer?

The agent reads the installed version from `apps/backend/package.json`. From 2.11.0 the OpenTelemetry SDK packages are installed with a new project and only the exporter is added; on an older 2.x it installs `@opentelemetry/sdk-node`, `@opentelemetry/resources`, `@opentelemetry/sdk-trace-node` and `@opentelemetry/instrumentation-pg` as well, and the `http.allowedQueryParams` option needs 2.22.0.

### Will query strings with tokens end up in my traces?

Not with the request on this page. `http.allowedQueryParams` names the few parameters a store reads and every other value is reported as `REDACTED`. Passing `"*"` reports the full query string, which the agent does not do unless you ask.

### What about the Next.js storefront?

It is out of scope for this run; the prompt says to change nothing in `apps/storefront`. The storefront's traces are a separate job with Next.js's own instrumentation file, and a follow-up message to the same session can start it on the same branch or a new one.

## More Medusa jobs

- [Send an Order Confirmation Email from a Medusa Backend](https://getrush.ai/run/add-order-confirmation-email/medusa/)
- [Add Product Reviews to a Medusa Store](https://getrush.ai/run/add-product-reviews/medusa/)
- [Add Rate Limiting to a Medusa Store API](https://getrush.ai/run/add-rate-limiting/medusa/)

## The same job on other stacks

- [Add OpenTelemetry Tracing to an Express and Mongoose API](https://getrush.ai/run/add-opentelemetry/mongoose/)
- [Add OpenTelemetry Tracing to a NestJS Service](https://getrush.ai/run/add-opentelemetry/nestjs/)
- [Add OpenTelemetry Tracing to a Phoenix App](https://getrush.ai/run/add-opentelemetry/phoenix/)

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