> ## 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 concepts and terminology in Lemma

Four nouns describe everything in Lemma. They are 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 style={{ display: "flex", flexDirection: "column", alignItems: "center", padding: "28px 0", gap: 0, fontFamily: "ui-monospace, 'SF Mono', Menlo, monospace" }}>
  <div style={{ background: "#f5f3ff", border: "1.5px solid #8b5cf6", borderRadius: 10, padding: "10px 20px", textAlign: "center", minWidth: 230 }}>
    <div style={{ fontSize: 13, fontWeight: 700, color: "#5b21b6" }}>support-agent</div>
    <div style={{ fontSize: 11, fontWeight: 600, color: "#7c3aed", marginTop: 2 }}>trace root</div>
    <div style={{ fontSize: 10.5, color: "#9ca3af", marginTop: 3 }}>input · output · timing</div>
  </div>

  <div style={{ width: 1.5, height: 22, background: "#d1d5db" }} />

  <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: "#d1d5db", zIndex: 0 }} />

    <div style={{ display: "flex", flexDirection: "column", alignItems: "center", paddingTop: 0 }}>
      <div style={{ width: 1.5, height: 22, background: "#d1d5db" }} />

      <div style={{ background: "#eff6ff", border: "1.5px solid #60a5fa", borderRadius: 10, padding: "9px 16px", textAlign: "center", minWidth: 170 }}>
        <div style={{ fontSize: 12, fontWeight: 600, color: "#1d4ed8" }}>draft-reply</div>
        <div style={{ fontSize: 10.5, color: "#9ca3af", 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: "#d1d5db" }} />

      <div style={{ background: "#f0fdf4", border: "1.5px solid #4ade80", borderRadius: 10, padding: "9px 16px", textAlign: "center", minWidth: 170 }}>
        <div style={{ fontSize: 12, fontWeight: 600, color: "#15803d" }}>search\_docs</div>
        <div style={{ fontSize: 10.5, color: "#9ca3af", 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 [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: 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).

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

<CardGroup cols={2}>
  <Card title="Trace contract" icon="https://mintcdn.com/lemma/XXIddB3j9y0FvoxN/icons/file-check.svg?fit=max&auto=format&n=XXIddB3j9y0FvoxN&q=85&s=9eb204cd5a25fc56737badccc0597f87" href="/reference/trace-contract" width="24" height="24" data-path="icons/file-check.svg">
    The exact shape Lemma reads.
  </Card>

  <Card title="Setup" icon="https://mintcdn.com/lemma/XXIddB3j9y0FvoxN/icons/wrench.svg?fit=max&auto=format&n=XXIddB3j9y0FvoxN&q=85&s=6cebadb38a3d75846abfda5189f746a9" href="/tracing/instrumentation/setup" width="24" height="24" data-path="icons/wrench.svg">
    Install the SDK and point it at Lemma.
  </Card>
</CardGroup>