Trace serverless runtimes
Keep tracing alive through bundlers and runtimes that freeze.
Bundled and serverless tracing requires two things: one server-side SDK instance must load before traced clients in a TypeScript bundle, and completed roots must flush before a serverless runtime freezes. Use this page for bundlers such as Next.js and for serverless runtimes that can stop after responding.
TypeScript bundlers
Load tracing from the runtime’s instrumentation or bootstrap path before you import traced model clients. Confirm the bundler puts that module in the server runtime.
A bundled runtime can give each entry point its own copy of judgeval or
@opentelemetry/api. The copy you initialized is then not the copy your handler
uses, so nothing records. Keep one server-side copy of both packages.
For Next.js:
export default {
serverExternalPackages: ["judgeval", "@opentelemetry/api"],
};Log once at initialization. A second log when a handler loads points to a second copy.
In TypeScript, auto-instrumentation needs all three of the following: a
preloaded instrumentation file, OpenTelemetry instrumentations registered on
Tracer before Tracer.init(), and a CommonJS build. See
Instrument your agent for the setup.
Serverless runtimes
A serverless runtime can freeze as soon as it sends the response, which may
discard spans still waiting to export. In TypeScript, await
Tracer.forceFlush() after the root ends and before the handler returns. In
Python, call Tracer.force_flush() at the same point. Initialize the tracer once
per runtime instance and shut it down only when the process stops, not after
each request.
Verify
First run the shared verification checklist. Then deploy and export a full trace on a cold call, meaning the first request after the runtime spins up. The init log should appear once, and the completed trace should arrive before the runtime freezes. Silent export loss is the failure mode here: the app works while the platform shows nothing.
Troubleshooting
| Symptom | Check |
|---|---|
| Tracing initializes but handlers emit nothing | Confirm the bundle uses one server-side copy of judgeval and @opentelemetry/api. |
| Warm calls work but cold calls disappear | Load instrumentation from the runtime bootstrap path before traced clients. |
| The application responds but traces are missing | Await a flush after the root ends and before the runtime can freeze. |
| Initialization logs appear per request | Initialize once per runtime instance rather than inside each handler. |
Related pages
- Activate the root span
- Streaming for handlers that return a response before generation ends
- Durable work for serverless handlers that enqueue work for a later worker