> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://respan.ai/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://respan.ai/docs/_mcp/server.

# Tracing quickstart

Tracing records each step of your AI app, such as LLM calls, tool runs, and agent steps, as a tree of spans, so you can debug failures and see where time and cost go. The Respan SDK traces the major LLM SDKs automatically once you initialize it.

## Set up with your coding agent

Paste this prompt into Claude Code, Cursor, Codex, or any coding agent:

```
Help me set up Respan tracing: fetch and follow https://respan.ai/docs/agent-setup.md
```

To set it up yourself, follow the [steps below](#step-by-step).

## Step by step

#### Create an API key

In the [platform](https://platform.respan.ai), go to **Gateway** › **API keys** and click **New key**. Pick **Production** or **Test**, keep the default permissions, and click **Create**.

![The Create new key dialog with Name, Environment (Production or Test), and Permissions: Read, Write, Gateway, and Admin](/docs/_fern-img/1780e946301a96a6ac3f872649a2639a6e460fd0d24a63156dac176abadb66d8.webp)![The Create new key dialog with Name, Environment (Production or Test), and Permissions: Read, Write, Gateway, and Admin](/docs/_fern-img/d667c8cacacbf220f2faa497ee1229ff4b8eb6f99bb04d90d8c407a8f66e01b8.webp)

Click **Copy**, then **Done**. You won't see the key again, so save it now:

```bash
export RESPAN_API_KEY="your-respan-api-key"
```

#### Install and initialize the SDK

Install the Respan SDK alongside your LLM SDK. Initialize Respan once, before your first model call.

#### Python

Requires Python 3.11 to 3.13.

```bash
pip install respan-ai openai
```

**`app.py`**

```python app.py
from openai import OpenAI
from respan import Respan, workflow

respan = Respan()  # reads RESPAN_API_KEY
client = OpenAI()  # reads OPENAI_API_KEY

@workflow(name="support_agent")
def support_agent(question: str) -> str:
    response = client.chat.completions.create(
        model="gpt-5.5",
        messages=[{"role": "user", "content": question}],
    )
    return response.choices[0].message.content

print(support_agent("How do I rotate my API key?"))
```

#### TypeScript

```bash
npm install @respan/respan openai
```

**`app.mts`**

```typescript app.mts
import OpenAI from "openai";
import { Respan } from "@respan/respan";

const respan = new Respan(); // reads RESPAN_API_KEY
await respan.initialize();
const client = new OpenAI(); // reads OPENAI_API_KEY

await respan.withWorkflow({ name: "support_agent" }, async () => {
  const response = await client.chat.completions.create({
    model: "gpt-5.5",
    messages: [{ role: "user", content: "How do I rotate my API key?" }],
  });
  console.log(response.choices[0].message.content);
});
```

Calls made with the OpenAI, Anthropic, AWS Bedrock, Vertex AI, and Together AI SDKs are traced automatically, plus Google GenAI and Ollama in Python, and Cohere, OpenRouter, and Writer in TypeScript. The workflow wrapper groups the calls inside it into one trace.

Using an agent framework such as OpenAI Agents, LangChain, or the Vercel AI SDK? Find its guide in [Integrations](/docs/integrations/overview).

#### Run your app

```bash
export OPENAI_API_KEY="your-openai-api-key"
python app.py        # TypeScript: npx tsx app.mts
```

The SDK sends spans in the background and flushes them when the process exits. In serverless functions, call `respan.flush()` (`await respan.flush()` in TypeScript) before you return.

#### See the trace in Logs

Go to **Observability** › **Logs**. Open the grouping menu, which shows **Spans** by default, and pick **Traces**. Click your `support_agent` trace.

The side panel shows the span tree with each span's duration, tokens, and cost. Click a span to see its input and output.

![The trace side panel: a span tree for support\_agent with classify\_intent, openai.chat, search\_docs, write\_reply, and anthropic.chat, each with its duration, tokens, and cost, next to the selected support\_agent span's input and output](/docs/_fern-img/50285146d931a073f84c2a81afebd1a8a16cd668cfeb9aa50bb72312ab3a7a3f.webp)![The trace side panel: a span tree for support\_agent with classify\_intent, openai.chat, search\_docs, write\_reply, and anthropic.chat, each with its duration, tokens, and cost, next to the selected support\_agent span's input and output](/docs/_fern-img/193ed52b112fe51946073cdc689ce4f1bb006c68a0f8902c4c22c000c021ac7c.webp)

Don't see it? Widen the time range. Traces sent with a **Test** key show under **Test**, so set the environment switch to **Test** or **All environments**. See [Inspect spans and traces](/docs/documentation/features/observe/view-debug-traces).

## Key terms

The grouping menu in Logs switches between these views.

| Term       | What it is                                                                         |
| ---------- | ---------------------------------------------------------------------------------- |
| **Span**   | One recorded operation, such as an LLM call, a tool run, or a function you wrapped |
| **Trace**  | All the spans from one request or workflow run, linked into a tree                 |
| **Thread** | Spans that share a thread ID, such as the turns of one conversation                |