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

# Concepts

> Understand the key concepts in Muxx—traces, spans, generations, and more.

Before diving deeper into Muxx, it's helpful to understand the core concepts that power the platform.

## Traces

A **trace** represents a complete unit of work in your application. For example, a single API request to your server that involves multiple LLM calls would be one trace.

Traces help you understand the full picture of what happened during a request, including all the LLM calls made along the way.

## Spans

A **span** is a single operation within a trace. Spans can be nested to represent parent-child relationships. For example:

```text theme={null}
Trace: "Summarize Document"
|-- Span: "Extract Key Points"
|   |-- Generation: GPT-4o call
|-- Span: "Generate Summary"
|   |-- Generation: GPT-4o call
|-- Span: "Format Output"
```

Spans help you break down complex operations and identify where time is being spent.

## Generations

A **generation** is a single LLM API call. It captures:

* **Input** - The messages/prompt sent to the model
* **Output** - The response from the model
* **Model** - Which model was used (e.g., `gpt-4o`, `claude-3-5-sonnet`)
* **Provider** - The LLM provider (OpenAI, Anthropic, Google)
* **Tokens** - Input and output token counts
* **Cost** - Calculated cost based on token usage
* **Latency** - How long the request took

## Projects

A **project** in Muxx represents a single application or environment. Each project has:

* Its own API key
* Separate log storage
* Independent rate limits and settings
* Provider API keys configured per project

Common patterns:

* One project per application
* Separate projects for development, staging, and production

## Organizations

An **organization** is a container for projects and team members. Organizations handle:

* Billing and subscription
* Team member access and roles
* Project organization

## Gateway vs SDK

| Feature        | Gateway         | SDK                          |
| -------------- | --------------- | ---------------------------- |
| Setup          | Change base URL | Install package, wrap client |
| Code changes   | Minimal         | Some                         |
| Tracing depth  | Request-level   | Trace/span-level             |
| Caching        | Yes             | No (direct to provider)      |
| Rate limiting  | Yes             | No (direct to provider)      |
| Latency impact | Minimal         | None (async batching)        |

**Use Gateway when** you want caching, rate limiting, or minimal code changes.

**Use SDK when** you need deep tracing with custom spans and decorators.

**Use both** for the complete feature set.