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 with this body:
{
"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"
}
]
}- 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 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.
The use case this job follows, with its automation and trigger: Hand off a long task.
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.