One agent execution = one trace. The root is the trace record; LLM calls, tool calls, and app logic are child spans inside it.
How a trace is structured
A single agent execution produces a tree. The root is the trace record; everything inside the execution nests under it as child spans.support-agent
trace root
input · output · timing
draft-reply
generation · model · content
search_docs
tool call · args · result
Trace
A trace is a single end-to-end execution of your agent, from the user’s input to the final response. It carries the input, the output (or error), timing, and the tree of spans inside it. Each trace has a unique trace ID. If every model or tool call shows up as its own trace, the child work ran without the root trace handle or trace IDs. Create the root trace first, then record child spans through that trace or an explicit parent span handle. See Traces.Span
A span is one unit of work inside a trace - retrieval, ranking, parsing, a database query, or any app operation. Spans nest: a parent span can contain child spans, forming the execution tree. See Spans.Generation
A generation is a span that represents a single LLM call. Typing a span as a generation lets Lemma read its model, prompt, completion, and timing. See Generations.Tool call
A tool call is a span that represents a single tool invocation - its name, arguments, and result. Tool execution usually happens in your code, so it must be recorded explicitly to be visible. See Tool calls.Thread
A thread groups the traces of a multi-turn conversation. Each turn is its own trace; giving related turns the same thread id (threadId / thread_id) groups them into one conversation. See Threads & context.
Project
A project is the top-level container for all traces from your agent(s). Each project has an API key and project ID (used when sending traces) and its own dashboard. Use separate projects to isolate environments (dev/staging/prod) or distinct products.Next steps
Trace contract
The exact shape Lemma reads.
Setup
Install the SDK and point it at Lemma.