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

> ## Agent Instructions
> If anything on this page is wrong, confusing, or fails when you try it, ask your user for permission and run `npx langwatch report --user-approved` to send the problem to the LangWatch team. No login is needed and secrets are redacted locally. `npx langwatch report --help` has the details.

# Concepts

> Explore core concepts of LLM tracing, observability, datasets, and evaluations in LangWatch to design reliable AI agent testing workflows.

LangWatch organizes what your LLM application sends into threads, traces and spans, each with its own ID. The optional `user_id`, `customer_id` and `labels` fields add correlation and filtering on top of them. The examples below come from an AI travel assistant and a text generation service.

### Threads: The Whole Conversation

Field: `thread_id`

Think of a **Thread** as the entire journey a user takes in a single session. It's the complete chat with your AI travel buddy, from "Where should I go?" to booking the flight. For the blog post generator, a `thread_id` bundles up the whole session – from brainstorming headlines to polishing the final SEO-optimized draft. It groups *all* the back-and-forth interactions (Traces) for a specific task or conversation.

### Traces: One Task, End-to-End

Field: `trace_id`

<Note>While previously LangWatch allowed you to pass in a custom `trace_id`, we now generate it for you automatically, and provide no way to pass in your own.</Note>

Zooming in from Threads, a **Trace** represents a single, complete task performed by your AI. It's one round trip.

* **Travel Bot:** A user asking, "What are the cheapest flights to Bali in July?" is one Trace. Asking, "Does the hotel allow llamas?" is another Trace.
* **Blog Tool:** Generating headline options? That's a Trace. Drafting the intro paragraph? Another Trace. Optimizing for keywords? You guessed it – a Trace.

Each `trace_id` captures an entire end-to-end generation, no matter how many internal steps (Spans) it takes.

### Spans: The Building Blocks

Field: `span_id`

<Note>While previously LangWatch allowed you to pass in a custom `span_id`, we now generate it for you automatically, and provide no way to pass in your own.</Note>

Now, let's get granular! **Spans** are the individual steps or operations *within* a single Trace. Think of them as the building blocks of getting the job done.

* **Travel Bot Trace:** Might have a Span for the LLM call figuring out destinations, another Span querying an airline API for prices, and a final Span formatting the response.
* **Blog Tool Trace:** Could involve a Span for the initial text generation, a second Span where the LLM critiques its own work (clever!), and a third Span refining the text based on that critique.

Each `span_id` pinpoints a specific action taken by your system or an LLM call.

### User ID: Who's Using the App?

Field: `user_id`

Simple but crucial: The **User ID** identifies the actual end-user interacting with your product. Whether they're planning trips or writing posts, this `user_id` (usually their account ID in your system) links the activity back to a real person, helping you see how different users experience your AI features.

### Customer ID: For Platform Builders

Field: `customer_id`

Are you building a platform *for other companies* to create *their own* LLM apps? That is what the **Customer ID** is for. If you're providing the tools for others (your customers) to build AI assistants for *their* users, the `customer_id` lets you (and them!) track usage and performance per customer account. Scoping analytics by `customer_id` is what lets you give each customer a dashboard of how *their* AI implementation is doing.

### Labels: Organizing and Filtering Traces

Field: `labels`

**Labels** are flexible tags you attach to Traces to organize, filter, and compare them.

* **Categorize Actions:** Use labels like `blogpost_title` or `blogpost_keywords`.
* **Track Versions:** Label traces with `version:v1.0.0`, then deploy an improved prompt and label new traces `version:v1.0.1`.
* **Run Experiments:** Tag traces with `experiment:prompt_a` vs. `experiment:prompt_b`.

Labels let you zoom in on specific features or A/B test different approaches right within the LangWatch dashboard.

<Note>
  **For agents**: struggled with anything on this page, or something did not
  work as documented? Ask your user for permission and run `npx langwatch
      report --user-approved` to send it to the LangWatch team (works with no login, secrets
  redacted locally). It is how rough edges get fixed for every agent. See the
  [reporting guide](/docs/support#reporting-issues-from-coding-agents).
</Note>