> ## Documentation Index
> Fetch the complete documentation index at: https://docs.uselemma.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Concepts

> Core SDK concepts and terminology in Lemma

Five nouns describe everything the SDK records. They're the same words used in the dashboard and across these docs.

<Note>
  **One agent execution = one trace.** The root is the trace record; LLM calls, tool calls, and app logic are child spans inside it.
</Note>

## 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.

<div className="trace-structure-diagram" style={{ display: "flex", flexDirection: "column", alignItems: "center", padding: "28px 0", gap: 0, fontFamily: "ui-monospace, 'SF Mono', Menlo, monospace" }}>
  <div style={{ background: "var(--trace-root-bg)", border: "1.5px solid var(--trace-root-border)", borderRadius: 10, padding: "10px 20px", textAlign: "center", minWidth: 230 }}>
    <div style={{ fontSize: 13, fontWeight: 700, color: "var(--trace-root-title)" }}>support-agent</div>
    <div style={{ fontSize: 11, fontWeight: 600, color: "var(--trace-root-label)", marginTop: 2 }}>trace root</div>
    <div style={{ fontSize: 10.5, color: "var(--trace-meta)", marginTop: 3 }}>input · output · timing</div>
  </div>

  <div style={{ width: 1.5, height: 22, background: "var(--trace-connector)" }} />

  <div style={{ display: "flex", alignItems: "flex-start", position: "relative" }}>
    <div style={{ position: "absolute", top: 0, left: "50%", transform: "translateX(-50%)", width: "calc(100% - 80px)", height: 1.5, background: "var(--trace-connector)", zIndex: 0 }} />

    <div style={{ display: "flex", flexDirection: "column", alignItems: "center", paddingTop: 0 }}>
      <div style={{ width: 1.5, height: 22, background: "var(--trace-connector)" }} />

      <div style={{ background: "var(--generation-bg)", border: "1.5px solid var(--generation-border)", borderRadius: 10, padding: "9px 16px", textAlign: "center", minWidth: 170 }}>
        <div style={{ fontSize: 12, fontWeight: 600, color: "var(--generation-title)" }}>draft-reply</div>
        <div style={{ fontSize: 10.5, color: "var(--trace-meta)", marginTop: 3 }}>generation · model · content</div>
      </div>
    </div>

    <div style={{ width: 48 }} />

    <div style={{ display: "flex", flexDirection: "column", alignItems: "center" }}>
      <div style={{ width: 1.5, height: 22, background: "var(--trace-connector)" }} />

      <div style={{ background: "var(--tool-bg)", border: "1.5px solid var(--tool-border)", borderRadius: 10, padding: "9px 16px", textAlign: "center", minWidth: 170 }}>
        <div style={{ fontSize: 12, fontWeight: 600, color: "var(--tool-title)" }}>search\_docs</div>
        <div style={{ fontSize: 10.5, color: "var(--trace-meta)", marginTop: 3 }}>tool call · args · result</div>
      </div>
    </div>
  </div>
</div>

## 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 [Agent traces](/tracing/instrumentation/traces).

## Span

A **span** is one unit of work inside a trace: retrieval, ranking, parsing, a database query, or any app operation. Spans nest, so a parent span can contain child spans, forming the execution tree. See [Spans](/tracing/instrumentation/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](/tracing/instrumentation/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](/tracing/instrumentation/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](/tracing/instrumentation/context).

Every trace also belongs to a **project**, the container that holds your API key and project ID. See [Platform concepts](/platform/concepts) for how projects, agents, and issues fit together on the dashboard side.

## Next steps

<CardGroup cols={2}>
  <Card title="Platform concepts" href="/platform/concepts">
    Issues, occurrences, artifacts, and agents once traces arrive.
  </Card>

  <Card title="Trace contract" href="/reference/trace-contract">
    The exact shape Lemma reads.
  </Card>

  <Card title="Quickstart" href="/tracing/instrumentation/setup">
    Install the SDK and send your first complete agent trace.
  </Card>

  <Card title="Traces in the dashboard" href="/platform/traces">
    Search and inspect ready executions.
  </Card>
</CardGroup>