Open LangSmith's dashboard for the first time and you'll see a list of "traces" inside something called a "project," and clicking one explodes into a tree of "runs." Three words, and once you know what each one means, the entire UI - and the SDK - stops feeling like a foreign language.
Run: the atomic unit
A run is the smallest thing LangSmith tracks. Every meaningful step your code takes becomes a run: one call to an LLM, one tool invocation, one retriever lookup, one graph node, or a plain function you've chosen to instrument yourself. Each run records its own inputs, outputs, start and end time, any error it threw, and whatever metadata or tags you attached to it - token counts and cost for an LLM run, the query and results for a retriever run, and so on.
Runs aren't flat. A run can contain child runs - an "agent" run might contain an LLM run, which triggers a tool run, which triggers another LLM run - and that nesting is exactly what makes a trace useful instead of just a pile of disconnected logs.
Trace: one request, end to end
A trace is the tree of runs produced by a single top-level request. When a user sends one message to your chatbot and your code fires off three LLM calls and a database lookup to answer it, all four of those runs - plus the top-level call that kicked them off - belong to one trace. Open a trace in the dashboard and you get a waterfall view: which step took how long, where the latency actually went, and exactly what each nested call saw and returned.
A project holds many traces; each trace is one request expanded into its full tree of nested runs.
Project: keeping environments apart
A project is a bucket that isolates traces from each other - typically one project for local development, one for staging, one for production, and sometimes a separate one just for evaluation runs. This matters more than it sounds: without it, a developer testing a broken prompt locally would pollute the same dashboard your production traffic shows up in, making it impossible to tell "a real user hit this bug" from "I was debugging something at my desk."
The full hierarchy, top to bottom, is Organization → Workspace → Project → Trace → Run. For a solo developer or small team, you'll mostly live at the project level and below; the organization/workspace layers exist for managing access across a bigger team.
Why this structure earns its keep
The nesting isn't just visual sugar. Because every run records its own timing, you can look at a slow trace and immediately see which single nested run ate the latency - was it the LLM call, or the retriever, or a tool that hung? Because every run records its own inputs and outputs, you can click into the exact step that produced a wrong answer instead of re-reading your entire codebase trying to guess. And because traces are grouped by project, you can compare "what production actually did this week" against "what I tested locally" without one contaminating the other.
What's next
Reading about traces only gets you so far - the next guide walks through wiring tracing into an actual app, so you can watch your own runs show up in the dashboard in real time.