Skip to main content
Most “tracing isn’t working” reports are one of a handful of silent failures: the app runs fine, no error is thrown, but spans never arrive. Find your symptom below.

​
No traces appear at all

The SDK ran, but nothing reached AgentMark.

​
The env vars weren’t loaded when the app ran

AGENTMARK_API_KEY / AGENTMARK_APP_ID decide where traces go, and Node does not load .env by itself. If the process started without them, the SDK has nowhere to send to. 
# Load .env explicitly
node --env-file=.env src/agent.ts        # Node 20.6+
# or: set -a; . ./.env; set +a; npm run agent
Confirm the values are present at construction time (console.log(!!process.env.AGENTMARK_API_KEY) right before new AgentMarkSDK(...)). In local development, agentmark dev receives traces at http://localhost:9418 automatically — no key needed.

​
A short-lived script exited before spans flushed

Spans are batched, so a CLI, serverless handler, or cron job can exit before the batch is sent. Disable batching and flush on the way out: 
const tracer = sdk.initTracing({ registerGlobally: true, disableBatch: true });
// ... your work ...
await tracer.forceFlush();
await tracer.shutdown();

​
Traces appear, but the model span is missing

You see your custom spans (span(), observe()), but the generation span — model name, token usage, input/output — is absent. Two causes, often together.

​
registerGlobally: true is missing

The AI SDK emits the model span through the global OpenTelemetry tracer. AgentMark’s tracer stays isolated by default so it never clobbers an existing OTel setup in your app — which means that without registerGlobally: true, the model span goes to a no-op tracer and silently vanishes while your custom spans keep working. 
const tracer = sdk.initTracing({ registerGlobally: true });
Pass it unless your app already registers its own global OTel provider.

​
(Vercel AI SDK) telemetry isn’t enabled on the call

Every generateText / streamText / generateObject call must opt in, or it emits no spans: 
const { text } = await generateText({
  model: openai("gpt-4o-mini"),
  prompt,
  experimental_telemetry: { isEnabled: true },
});
When you render through AgentMark, enable it on format() and pass the result straight through: 
const input = await prompt.format({
  props: { name: "Alice" },
  telemetry: { isEnabled: true },
});
const { text } = await generateText(input);

​
Quick checklist

  • Nothing at all? → env vars loaded when the process started; for scripts, disableBatch: true + await tracer.shutdown().
  • Custom spans but no model span? → registerGlobally: true, and (Vercel AI SDK) experimental_telemetry: { isEnabled: true } on every call.
  • Local dev? → traces go to http://localhost:9418; make sure agentmark dev is running.

​
Still stuck?

For errors with an explicit message (model not registered, 401, MCP server not found, …), see the error reference. Otherwise open an issue on GitHub with your SDK versions and a minimal reproduction.

​
Have Questions?

We’re here to help! Choose the best way to reach us: