Export traces from serverless

SDK 0.6.0 atlanai SDK buffers spans in a background batch of 64 spans or five seconds, whichever comes first. Use this guide when your TypeScript process exits or freezes before that batch exports, as in functions, Workers, CLIs, and jobs, because those spans are lost. For a Python script or job, call client.flush() in a finally block instead.

Before you begin

Before you start, make sure you have:

SDK: @atlanai/sdk installed, as in Install atlanai SDK.
Tracing: a working init call that exports traces, as in Trace your first agent run.
Runtime: Node 20 or later, or Cloudflare Workers with the nodejs_compat flag.
Credentials: an API key and workspace ID, passed to init() where the runtime has no environment variables.

Export per span

Set exportMode: "immediate" to replace the batcher with per-span export. Use it whenever the process lifetime is one request.

import { init } from "@atlanai/sdk/tracing";

const client = init({
  serviceName: "support-rover",
  apiKey: process.env.ATLAN_API_KEY,
  workspaceId: process.env.ATLAN_WORKSPACE_ID,
  exportMode: "immediate",
});

Still call flush() before returning, because the export itself is asynchronous. ATLAN_DEBUG=true also forces immediate mode, so debug runs surface a rejected export straight away.flush() rejects, or raises in Python, if any export from this client has failed, not only the export it just forced. The failure count never resets, so after one failed export every later flush() rejects. Check client.exportHealth (client.export_health in Python) for the failure count and last error.

Keep instance alive

Pass waitUntil so the runtime keeps the instance alive until export finishes instead of freezing it mid-request.

Cloudflare Workers
Vercel
CLI or job

export default {
  async fetch(request, env, ctx) {
    const client = init({
      serviceName: "support-rover",
      apiKey: env.ATLAN_API_KEY,
      workspaceId: env.ATLAN_WORKSPACE_ID,
      exportMode: "immediate",
      waitUntil: (promise) => ctx.waitUntil(promise),
    });

    const response = await handle(request);
    // Rides ctx.waitUntil, so the response does not block on export.
    // flush() rejects once any export from this client has failed, and
    // init() returns the same client for the isolate's lifetime. Catch
    // it, or the Worker logs an unhandled rejection.
    client.flush().catch(() => console.warn("Atlan export failed", client.exportHealth));
    return response;
  },
};

Workers have no ambient environment, so ATLAN_* variables are not readable. Pass apiKey, workspaceId, and every other option through init() from the env binding.

On the Node runtime, use after from next/server.

import { after } from "next/server";

after(() => client.flush().catch(() => console.warn("Atlan export failed", client.exportHealth)));

Node runs a best-effort flush on beforeExit. An explicit flush is reliable.

try {
  await runJob();
} finally {
  await client.flush(); // or client.shutdown() on final exit
}

If runJob() throws and the export also fails, the flush() error replaces the original one. Wrap flush() in its own try to keep both.

Bundle for Cloudflare Workers

Wrangler gets what it needs from compatibility_flags = ["nodejs_compat"] with a recent compatibility_date. Skip this step unless you bundle with esbuild directly.

esbuild worker.mjs --bundle --format=esm --platform=node \
  --main-fields=module,main \
  --conditions=workerd,module,import \
  --banner:js='import { createRequire as __cr } from "node:module"; var require = __cr(import.meta?.url ?? "file:///worker.mjs");'

Flag	Why
`--platform=node`	Externalizes Node builtins, which `nodejs_compat` provides at runtime.
`--conditions=workerd,module,import`	Custom conditions drop esbuild’s implicit `module` condition. Without it, OpenTelemetry packages resolve to CJS whose top-level evaluation breaks Workers.
`--main-fields=module,main`	Some OpenTelemetry packages have no `exports` map, and node-platform esbuild would otherwise prefer CJS `main`.
`--banner:js` with `createRequire`	Satisfies stray `require()` calls in CJS-converted dependencies.

The OTLP exporter chain loads lazily, so injecting your own spanExporter keeps Worker startup clean.

Verify export

Deploy, trigger one request, then open Atlan Trident and confirm the trace appears for that service_name. A 200 from your handler does not prove the export completed, because a frozen instance returns successfully while dropping the batch. Check the trace, not the response.If the trace is missing, see init() disables tracing and no traces are exported.

Troubleshooting

If traces are missing from short-lived processes, or init() reports a missing workspace in Workers, see Install and setup errors.

Next steps

Send and verify traces: confirm ingestion end to end.

Register and manage agents

Give agents business context

Observe agent runs

Evaluate and improve agents

Track agent cost

Export traces from serverless

Before you begin

Troubleshooting

Next steps

See also