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

# First Trace

> Trace your first LLM call with MutagenT

# Your First Trace

This guide walks you through tracing your first LLM call. By the end, you will see real trace data in your MutagenT dashboard.

## Prerequisites

* MutagenT CLI installed and authenticated (`mutagent auth login`)
* An API key (`mt_` prefix) -- see [API Keys](/quickstart/api-keys)
* An existing project that uses an LLM framework

## How Tracing Works

<Mermaid>
  sequenceDiagram
  participant App as Your App
  participant Int as Integration Package
  participant SDK as @mutagent/sdk
  participant API as api.mutagent.io

  App->>Int: LLM call (e.g., chat.completions.create)
  Int->>SDK: startSpan() / endSpan()
  SDK->>SDK: Buffer spans (batch of 10 or 5s flush)
  SDK->>API: POST /api/traces (batch)
  API-->>SDK: 200 OK
</Mermaid>

## Step 1: Generate Integration Code

Run `mutagent integrate` in your project directory. The CLI detects your framework and generates the code you need.

<CodeGroup>
  ```bash OpenAI theme={null}
  mutagent integrate openai
  ```

  ```bash LangChain theme={null}
  mutagent integrate langchain
  ```

  ```bash Vercel AI theme={null}
  mutagent integrate vercel-ai
  ```

  ```bash LangChain theme={null}
  mutagent integrate langchain
  ```
</CodeGroup>

The CLI outputs the integration code and the package to install. Follow the instructions it provides.

## Step 2: Install the Integration Package

Install the integration package for your framework.

<CodeGroup>
  ```bash OpenAI theme={null}
  bun add @mutagent/openai @mutagent/sdk
  ```

  ```bash LangChain theme={null}
  bun add @mutagent/langchain @mutagent/sdk
  ```

  ```bash Vercel AI theme={null}
  bun add @mutagent/vercel-ai @mutagent/sdk
  ```

  ```bash LangGraph theme={null}
  bun add @mutagent/langgraph @mutagent/sdk
  ```
</CodeGroup>

## Step 3: Set Your API Key

Set the `MUTAGENT_API_KEY` environment variable. The SDK reads it automatically.

```bash theme={null}
# .env
MUTAGENT_API_KEY=mt_xxxxxxxxxxxx
```

<Tip>
  If `MUTAGENT_API_KEY` is set in your environment, tracing initializes lazily on the first span -- no explicit `initTracing()` call needed. For more control, call `initTracing()` explicitly at startup.
</Tip>

## Step 4: Add the Integration Code

Add the generated integration code to your LLM calls. Each integration follows the same pattern: initialize tracing, then use the framework adapter.

<Tabs>
  <Tab title="OpenAI (TypeScript)">
    ```typescript theme={null}
    import OpenAI from 'openai';
    import { observeOpenAI } from '@mutagent/openai';
    import { initTracing } from '@mutagent/sdk/tracing';

    // Initialize tracing (or set MUTAGENT_API_KEY env var for auto-init)
    initTracing({ apiKey: process.env.MUTAGENT_API_KEY! });

    // Wrap the OpenAI client for automatic tracing
    const client = observeOpenAI(new OpenAI({
      apiKey: process.env.OPENAI_API_KEY,
    }));

    const response = await client.chat.completions.create({
      model: 'gpt-4o',
      messages: [{ role: 'user', content: 'What is observability?' }],
    });
    ```
  </Tab>

  <Tab title="OpenAI (Python)">
    ```bash theme={null}
    pip install mutagent-openai
    ```

    ```python theme={null}
    import os
    from mutagent.tracing import init_tracing
    from mutagent_openai import MutagentOpenAI

    init_tracing(api_key=os.environ["MUTAGENT_API_KEY"])

    client = MutagentOpenAI(api_key=os.environ["OPENAI_API_KEY"])

    response = client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": "What is observability?"}],
    )
    print(response.choices[0].message.content)
    ```
  </Tab>

  <Tab title="Anthropic (Python)">
    ```bash theme={null}
    pip install mutagent-anthropic
    ```

    ```python theme={null}
    import os
    from anthropic import Anthropic
    from mutagent_anthropic import wrap_anthropic
    from mutagent.tracing import init_tracing

    init_tracing(api_key=os.environ["MUTAGENT_API_KEY"])

    client = wrap_anthropic(Anthropic())

    msg = client.messages.create(
        model="claude-opus-4-5",
        max_tokens=1024,
        messages=[{"role": "user", "content": "What is observability?"}],
    )
    print(msg.content[0].text)
    ```
  </Tab>

  <Tab title="LangChain">
    ```typescript theme={null}
    import { initTracing } from '@mutagent/sdk/tracing';
    import { MutagentCallbackHandler } from '@mutagent/langchain';
    import { ChatOpenAI } from '@langchain/openai';

    initTracing({ apiKey: process.env.MUTAGENT_API_KEY! });

    const handler = new MutagentCallbackHandler();
    const llm = new ChatOpenAI({ model: 'gpt-4o' });

    const response = await llm.invoke('What is observability?', {
      callbacks: [handler],
    });
    ```
  </Tab>

  <Tab title="Vercel AI">
    ```typescript theme={null}
    import { initTracing } from '@mutagent/sdk/tracing';
    import { createMutagentMiddleware } from '@mutagent/vercel-ai';
    import { wrapLanguageModel, generateText } from 'ai';
    import { openai } from '@ai-sdk/openai';

    initTracing({ apiKey: process.env.MUTAGENT_API_KEY! });

    const model = wrapLanguageModel({
      model: openai('gpt-4o'),
      middleware: createMutagentMiddleware(),
    });

    const { text } = await generateText({
      model,
      prompt: 'What is observability?',
    });
    ```
  </Tab>

  <Tab title="Mastra">
    ```typescript theme={null}
    // mastra.config.ts
    import { initTracing } from '@mutagent/sdk/tracing';
    import { defineConfig } from '@mastra/core';

    initTracing({ apiKey: process.env.MUTAGENT_API_KEY! });

    export default defineConfig({
      agents: {
        'my-agent': {
          name: 'My Agent',
          model: 'gpt-4o',
          instructions: 'You are a helpful assistant.',
        },
      },
    });
    ```
  </Tab>
</Tabs>

### `initTracing()` Options

| Option            | Type      | Default                   | Description                                        |
| ----------------- | --------- | ------------------------- | -------------------------------------------------- |
| `apiKey`          | `string`  | --                        | **Required.** Your MutagenT API key (`mt_` prefix) |
| `endpoint`        | `string`  | `https://api.mutagent.io` | API endpoint URL                                   |
| `environment`     | `string`  | --                        | Environment name (e.g., `production`, `staging`)   |
| `batchSize`       | `number`  | `10`                      | Number of spans to buffer before flushing          |
| `flushIntervalMs` | `number`  | `5000`                    | Flush interval in milliseconds                     |
| `debug`           | `boolean` | `false`                   | Log span start/end events to console               |
| `source`          | `string`  | `"sdk"`                   | Source identifier for traces                       |

## Step 5: Run Your Application

Run your application as you normally would. The integration sends traces to MutagenT automatically in the background, batching spans and flushing every 5 seconds or when 10 spans accumulate.

```bash theme={null}
bun run dev
```

## Step 6: View Your Traces

Open the MutagenT dashboard at [app.mutagent.io](https://app.mutagent.io) to see your traces, or use the CLI.

```bash theme={null}
mutagent traces list
```

You should see your LLM call with:

* Input prompt and output response
* Model used and token counts
* Latency and timing data
* Span hierarchy (parent/child relationships)

<Note>
  Traces are sent asynchronously in batches and typically appear within a few seconds. If you do not see traces, check that your `MUTAGENT_API_KEY` is valid with `mutagent auth status`.
</Note>

## Graceful Shutdown

For server applications or scripts that exit after tracing, call `shutdownTracing()` to flush remaining buffered spans:

```typescript theme={null}
import { shutdownTracing } from '@mutagent/sdk/tracing';

// Before your process exits
await shutdownTracing();
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Manage Prompts" icon="file-lines" href="/platform/prompts/overview">
    Version and organize your prompts
  </Card>

  <Card title="Run Evaluations" icon="flask" href="/platform/evaluations/overview">
    Measure prompt quality with metrics
  </Card>

  <Card title="Optimize" icon="bolt" href="/platform/optimization/overview">
    Automatically improve your prompts
  </Card>

  <Card title="All Integrations" icon="plug" href="/integrations/overview">
    See all supported frameworks
  </Card>
</CardGroup>