Capture Your First Trace

Catalyst Tracing captures the full execution of your AI apps and agents: LLM calls, tool calls, framework steps, and any custom spans you add. Drop the SDK into your app, point it at Catalyst, and traces start flowing. This guide gets you from zero to a captured trace. The example uses OpenAI because it is the smallest end-to-end setup. The same flow works for Anthropic, LangChain, LangGraph, the Vercel AI SDK, OpenAI Agents, LiveKit Agents, Pydantic AI, and the other supported integrations. To get started with Catalyst, create a free account at inference.net.

Choose a setup path

Installing with AI is the quickest. Use the manual flow if you want to review each change yourself.

Install with AI
Install manually

Use the Inference CLI to launch a coding agent like Claude Code to install the tracing SDK, configure export, and wire up your existing LLM clients.

Install the CLI and authenticate

Install the Inference CLI globally and log in. Your browser will open to authenticate.

npm install -g @inference/cli && inf auth login

Run tracing instrumentation in your project

From your project root, run instrumentation in tracing mode.

cd /path/to/your/project && inf instrument --mode tracing

The command guides you through the following workflow:

Select a coding agent: Claude Code, OpenCode, or Codex.
Scan your codebase for LLM clients and agent frameworks.
Install the tracing SDK and configure export to Catalyst.
Wire setup() into your app entrypoint so spans start before clients are constructed.
Add stable service and agent identity so traces group cleanly in the dashboard.
Review the generated changes before applying them.

Pick both instead of tracing if you also want to route requests through the Catalyst Gateway in the same pass.

Run your app

Run your application how you normally would. Traces stream to Catalyst as your code executes.

View your trace

Open the dashboard and filter by your service name to see the captured trace tree.

Want the full canonical guide for this workflow? See Install with AI.

Use this path if you want to wire it up yourself. The example below uses OpenAI. For other providers and frameworks, see the Tracing integrations guide.

Install the SDK

bun add @inference/tracing openai

Configure export

Set the Catalyst traces endpoint and token before your app starts.

export CATALYST_OTLP_ENDPOINT="https://telemetry.inference.net"
# Get your API key from https://inference.net/dashboard/api-keys/
export CATALYST_OTLP_TOKEN="<your-token>"
export CATALYST_SERVICE_NAME="checkout-agent"
export CATALYST_SERVICE_VERSION="2026.04.28"

Use a stable CATALYST_SERVICE_NAME per deployed service. It makes traces easier to filter and compare across environments.

Initialize tracing early

Call setup() before constructing clients from instrumented SDKs.

import { setup } from "@inference/tracing";
import OpenAI from "openai";

const tracing = await setup({
  modules: { openai: OpenAI },
});

const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

const response = await client.chat.completions.create({
  model: "gpt-4o-mini",
  messages: [{ role: "user", content: "Reply with just the word hello." }],
  max_tokens: 16,
});

console.log(response.choices[0]?.message.content);
await tracing.shutdown();

If the process is short-lived, always call shutdown() before exit so batched spans are flushed.

View your trace

Open the dashboard and filter for your CATALYST_SERVICE_NAME. You’ll see an LLM span with input messages, output messages, model name, invocation parameters, finish reason, and token counts.

Need a different provider or framework? See Tracing integrations for OpenAI, Anthropic, LangChain, LangGraph, the Vercel AI SDK, OpenAI Agents, LiveKit, Claude Agent SDK, Pydantic AI, and more.

That’s it. Spans are streaming to Catalyst and your trace is ready to inspect.

What gets captured

Span data	Examples
Inputs and outputs	`input.value`, `output.value`
Messages	user, system, assistant, tool, and tool-result messages
Tool calls	tool names, IDs, JSON arguments, and tool results
Model metadata	model name, provider/system, invocation parameters
Usage	prompt, completion, total, and prompt-cache token counts
Agent structure	agent spans, framework spans, tool spans, graph/node spans
Errors	exception status and error details on failed spans

Next steps

Analyze your traces

Inspect trace trees in the dashboard and run Halo to find what to improve.

Add more integrations

Instrument Anthropic, LangChain, LangGraph, Vercel AI SDK, agent frameworks, and more.

Set agent identity

Add stable agent IDs so the Agents dashboard groups runs correctly.

Wrap custom work

Add spans around your own orchestration, retrieval, and routing code.

Get Started

Observe

Datasets

Eval

Train

Deploy

Platform

Choose a setup path

What gets captured

Next steps

Analyze your traces

Add more integrations

Set agent identity

Wrap custom work

Get Started

Observe

Datasets

Eval

Train

Deploy

Platform

Documentation Index

​Choose a setup path

​What gets captured

​Next steps

Analyze your traces

Add more integrations

Set agent identity

Wrap custom work

Choose a setup path

What gets captured

Next steps