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
An existing project that uses an LLM framework

How Tracing Works

Step 1: Generate Integration Code

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

mutagent integrate openai

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.

bun add @mutagent/openai @mutagent/sdk

Step 3: Set Your API Key

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

# .env
MUTAGENT_API_KEY=mt_xxxxxxxxxxxx

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.

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.

OpenAI
LangChain
Vercel AI
Mastra

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?' }],
});

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],
});

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?',
});

// 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.',
    },
  },
});

`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.

bun run dev

Step 6: View Your Traces

Open the MutagenT dashboard at app.mutagent.io to see your traces, or use the CLI.

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)

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.

Graceful Shutdown

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

import { shutdownTracing } from '@mutagent/sdk/tracing';

// Before your process exits
await shutdownTracing();

Next Steps

Manage Prompts

Version and organize your prompts

Run Evaluations

Measure prompt quality with metrics

Optimize

Automatically improve your prompts

All Integrations

See all supported frameworks

Getting Started

CLI

Integrations

Tracing

SDK

​Your First Trace

​Prerequisites

​How Tracing Works

​Step 1: Generate Integration Code

​Step 2: Install the Integration Package

​Step 3: Set Your API Key

​Step 4: Add the Integration Code

​initTracing() Options

​Step 5: Run Your Application

​Step 6: View Your Traces

​Graceful Shutdown

​Next Steps

Manage Prompts

Run Evaluations

Optimize

All Integrations

Your First Trace

Prerequisites

How Tracing Works

Step 1: Generate Integration Code

Step 2: Install the Integration Package

Step 3: Set Your API Key

Step 4: Add the Integration Code

`initTracing()` Options

Step 5: Run Your Application

Step 6: View Your Traces

Graceful Shutdown

Next Steps