TracingDistributed Tracing

Distributed Tracing

Visualize the full execution tree of your AI agents — every LLM call, tool call, and retrieval step.

What is Tracing?

A trace represents a single end-to-end execution of your agent. Each trace contains one or more spans — individual steps like LLM calls, tool invocations, or retrieval operations.

Traces give you full observability into:

  • Execution order and nesting (parent → child spans)
  • Timing and duration of every step
  • Token usage and cost per LLM call
  • Input/output data for debugging
  • Error tracking with stack traces

Quick Example

Wrap your agent execution in a trace, then create spans for each step. See the code panel → for a complete example.

1

Start a trace

Call startTrace() with a name and optional input. The SDK stores the trace ID internally.

2

Create spans for each step

Call startSpan() for each LLM call, tool call, or retrieval. Spans auto-link to the active trace.

3

End spans with results

Call endSpan() with output, token counts, and cost. The platform calculates duration automatically.

4

End the trace

Call endTrace() with the final output and status.

Viewing Traces

Go to Dashboard → Traces to see all traces. Click any trace to see the Tree View (execution graph) or Waterfall (timeline). Click any span for full input/output details.

⚡ Traces and spans are linked to your events via trace_id and span_id fields, so you can correlate events with the exact execution step that generated them.
ConfigurationTraces & Spans

Was this helpful?

Something wrong? Open an issue on GitHub
import { AIGodfather } from class="tk-str">'aigodfather'

const ai = new AIGodfather({
  apiKey: process.env.AIGODFATHER_API_KEY,
})

class=class="tk-str">"tk-cmt">// Start a trace for the full agent run
const traceId = await ai.startTrace({
  name: class="tk-str">'customer-support-agent',
  input: { query: class="tk-str">'How do I reset my password?' },
  tags: [class="tk-str">'support', class="tk-str">'password'],
})

class=class="tk-str">"tk-cmt">// LLM call span
const llmSpan = await ai.startSpan({
  name: class="tk-str">'classify-intent',
  type: class="tk-str">'llm',
  model: class="tk-str">'gpt-4o-mini',
  provider: class="tk-str">'openai',
  input: { prompt: class="tk-str">'Classify: How do I reset my password?' },
})

class=class="tk-str">"tk-cmt">// ... call OpenAI ...

await ai.endSpan(llmSpan, {
  output: { intent: class="tk-str">'password_reset' },
  status: class="tk-str">'success',
  prompt_tokens: 42,
  completion_tokens: 5,
  total_tokens: 47,
  cost_usd: 0.00012,
})

class=class="tk-str">"tk-cmt">// Tool call span
const toolSpan = await ai.startSpan({
  name: class="tk-str">'lookup-kb',
  type: class="tk-str">'retrieval',
  input: { query: class="tk-str">'password reset instructions' },
})

await ai.endSpan(toolSpan, {
  output: { docs: [class="tk-str">'Go to Settings > Security...'] },
  status: class="tk-str">'success',
})

class=class="tk-str">"tk-cmt">// End the trace
await ai.endTrace(traceId, {
  output: { response: class="tk-str">'Go to Settings > Security...' },
  status: class="tk-str">'success',
})