Spans

A span is one step inside a run. Use withSpan to wrap any block of code; the dashboard shows it in the run’s waterfall.

Kinds

Kind	For	Required fields
`llm`	Model calls	`model`, `inputTokens`, `outputTokens` (auto for supported providers)
`tool`	Functions the agent invokes (search, DB, API)	`toolName`
`retrieval`	Vector search, KB lookup, RAG retriever	—
`agent`	A nested sub-step rendered as an agent stage	—
`chain`	A chain / graph step (LangChain, LangGraph)	—
`function`	Generic instrumented function	—

Example — all fields

Node.js
Python

await trodo.withSpan({ kind: 'llm', name: 'chat.completions' }, async (span) => {
  // AUTO-populated when using OpenAI / Anthropic / Bedrock / Cohere / Gemini /
  // Vertex / Mistral / LangChain / LlamaIndex / Vercel AI SDK.
  // Set these manually only when calling the provider via raw fetch.
  span.setLlm({
    model: 'gpt-4o-mini',          // auto
    provider: 'openai',             // auto
    inputTokens: 120,               // auto (from response.usage)
    outputTokens: 64,               // auto
    cost: 0.00034,                  // auto (computed from tokens + model)
    temperature: 0.2,               // auto (from request body)
  });

  // Always manual:
  span.setInput({ prompt: '...' });
  span.setOutput({ completion: '...' });
  span.setAttribute('customer_tier', 'enterprise');

  try {
    return await openai.chat.completions.create({ ... });
  } catch (err) {
    span.setError({ type: 'RateLimitError', message: err.message }); // status = 'error'
    throw err;
  }
});

// Tool span — toolName is required:
await trodo.withSpan({ kind: 'tool', name: 'search_kb', toolName: 'search_kb' }, async (span) => {
  span.setInput({ query });
  const results = await kb.search(query);
  span.setOutput({ count: results.length });
  return results;
});

with trodo.span("chat.completions", kind="llm") as span:
    # AUTO-populated when using a supported framework (see list above).
    # Set manually only for raw HTTP / unsupported providers.
    span.set_llm(
        model="gpt-4o-mini",
        provider="openai",
        input_tokens=120,
        output_tokens=64,
        cost=0.00034,
        temperature=0.2,
    )

    span.set_input({"prompt": "..."})
    span.set_output({"completion": "..."})
    span.set_attribute("customer_tier", "enterprise")

    try:
        resp = openai.chat.completions.create(...)
    except Exception as e:
        span.set_error(type="RateLimitError", message=str(e))  # status = 'error'
        raise

with trodo.span("search_kb", kind="tool") as span:
    span.set_tool("search_kb")
    span.set_input({"query": query})
    results = kb.search(query)
    span.set_output({"count": len(results)})

Field reference

Setter	DB column	Auto-captured for supported frameworks?
`setInput(value)`	`input`	no — always manual
`setOutput(value)`	`output`	no — always manual
`setLlm({ model })`	`model`	yes
`setLlm({ provider })`	`provider`	yes
`setLlm({ inputTokens })`	`input_tokens`	yes
`setLlm({ outputTokens })`	`output_tokens`	yes
`setLlm({ cost })`	`cost`	yes (computed from tokens + model)
`setLlm({ temperature })`	`temperature`	yes
`setTool(name)`	`tool_name`	yes (LangChain, LlamaIndex tool calls)
`setError({ type, message })`	`error_type`, `error_message`, `status='error'`	yes (on thrown exceptions)
`setAttribute(key, value)`	`attributes.<key>`	no — always manual
`span.name`	`name`	yes (from the instrumented method name)
`span.kind`	`kind`	yes
`span.status`	`status`	yes (`ok` on success, `error` on throw)

Errors

A thrown exception inside withSpan sets status='error' plus error_type and error_message from the exception, then re-raises. Wrap with try/catch if you want to recover; the span is recorded either way.

Spans outside wrapAgent — emit spans from files / workers / services that run outside the callback.
Patterns — helpers (tool / llm / trace), trackLlmCall, feedback, custom attributes.

GETTING STARTED

TRACING

INTEGRATIONS

Kinds

Example — all fields

Field reference

Errors

Next

GETTING STARTED

TRACING

INTEGRATIONS

Documentation Index

​Kinds

​Example — all fields

​Field reference

​Errors

​Next

Kinds

Example — all fields

Field reference

Errors

Next