Skip to main content
When something isn’t behaving as expected — spans not appearing, runs not completing, export not firing — debug mode prints a log line for every significant internal event so you can see exactly what’s happening.

​
Enabling Debug Mode

Code API
import { enableDebugMode, disableDebugMode } from "@uselemma/tracing";

enableDebugMode();
// ... run your agent ...
disableDebugMode(); // optional
Environment variable
LEMMA_DEBUG=true node your-app.js
Both methods can be used together. The env var is checked at call time, so you can set it after the module is imported.

​
What Gets Logged

All output is prefixed with [LEMMA:trace-wrapper] or [LEMMA:processor] so you can filter it easily.

​
wrapAgent / wrap_agent

EventWhen it fires
span startedA new root span is opened for a run, with agent name, run ID, and autoEndRoot value
span ended via onCompleteonComplete / on_complete was called and ended the span (only when autoEndRoot: false)
onComplete called but span not endedonComplete was called but autoEndRoot is active or the span was already ended
span auto-ended after fn returnedThe wrapped function returned and the span was ended automatically
span ended on errorAn uncaught exception ended the span, with the error message

​
RunBatchSpanProcessor

EventWhen it fires
onStart: top-level run spanA new ai.agent.run root span was started, with span ID, run ID, and whether auto-end is on
onStart: child spanA child span was started and attributed to a run
onEnd: span endedAny span ended, with span name, run ID, whether it’s the top-level span, and whether it was skipped for export
onEnd: direct child endedA direct child of a root span ended, with remaining child count
onEnd: triggering auto-end of top-level spanAll direct children finished and the root span is being auto-ended
exporting batchA batch of spans is being sent to the exporter, with run ID and span count
force_flush calledforceFlush was called
shutdown calledshutdown was called

​
Example Output

Running a simple agent with debug mode enabled produces output like this: 
[LEMMA:trace-wrapper] span started { agentName: 'my-agent', runId: 'abc-123', autoEndRoot: true }
[LEMMA:processor] onStart: top-level run span { spanId: '...', runId: 'abc-123', autoEnd: true }
[LEMMA:processor] onStart: child span { spanName: 'gen_ai.chat', spanId: '...', runId: 'abc-123' }
[LEMMA:processor] onEnd: span ended { spanName: 'gen_ai.chat', spanId: '...', runId: 'abc-123', isTopLevel: false, skipped: false }
[LEMMA:trace-wrapper] span auto-ended after fn returned { runId: 'abc-123' }
[LEMMA:processor] onEnd: span ended { spanName: 'ai.agent.run', spanId: '...', runId: 'abc-123', isTopLevel: true, skipped: false }
[LEMMA:processor] exporting batch { runId: 'abc-123', spanCount: 2, force: false }

​
Checking Debug Mode State

import { isDebugModeEnabled } from "@uselemma/tracing";

console.log(isDebugModeEnabled()); // true or false
Debug mode is off by default and intended for local troubleshooting. It writes directly to stdout — avoid leaving it enabled in production.
For higher-level symptom-based guidance (trace cuts short, tool calls missing, Anthropic stream errors), see Common Issues.