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

# 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, Vercel Eve, OpenAI Agents, LiveKit Agents, PI AI, Pydantic AI, and the other [supported integrations](/integrations/traces/overview).

Either path below installs and wires up the Catalyst tracing SDK: [`@inference/tracing`](https://www.npmjs.com/package/@inference/tracing) on npm for TypeScript, or [`inference-catalyst-tracing`](https://pypi.org/project/inference-catalyst-tracing/) on PyPI for Python.

To get started with Catalyst, create a free account at [inference.net](https://inference.net/register).

## Choose a setup path

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

<Tabs>
  <Tab title="Install with AI">
    Use the [Inference CLI](/cli/overview) to launch a coding agent like [Claude Code](https://code.claude.com/docs/en/overview) to install the tracing SDK, configure export, and wire up your existing LLM clients.

    <Steps>
      <Step title="Install the CLI and authenticate">
        Install the Inference CLI globally and log in. Your browser will open to authenticate.

        <Metadata text="get-started/capture-first-trace-ai-auth" />

        ```bash theme={"system"}
        npm install -g @inference/cli && inf auth login
        ```
      </Step>

      <Step title="Run tracing instrumentation in your project">
        From your project root, run instrumentation in tracing mode.

        <Metadata text="get-started/capture-first-trace-ai-instrument" />

        ```bash theme={"system"}
        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.

        <Tip>
          Pick `both` instead of `tracing` if you also want to route requests through the Catalyst Gateway in the same pass.
        </Tip>
      </Step>

      <Step title="Run your app">
        Run your application how you normally would. Traces stream to Catalyst as your code executes.
      </Step>

      <Step title="View your trace">
        Open the [dashboard](https://inference.net/dashboard) and filter by your service name to see the captured trace tree.
      </Step>
    </Steps>

    <Note>
      Want the full canonical guide for this workflow? See [Install with AI](/integrations/install-with-ai).
    </Note>
  </Tab>

  <Tab title="Install manually">
    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](/integrations/traces/overview).

    <Steps>
      <Step title="Install the SDK">
        <CodeGroup>
          <Metadata text="get-started/capture-first-trace-manual-install-typescript" />

          ```bash TypeScript theme={"system"}
          bun add @inference/tracing openai
          ```

          <Metadata text="get-started/capture-first-trace-manual-install-python" />

          ```bash Python theme={"system"}
          pip install 'inference-catalyst-tracing[openai]'
          ```
        </CodeGroup>
      </Step>

      <Step title="Configure export">
        Set the Catalyst traces endpoint and token before your app starts.

        <Metadata text="get-started/capture-first-trace-manual-env" />

        ```bash theme={"system"}
        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"
        ```

        <Tip>
          Use a stable `CATALYST_SERVICE_NAME` per deployed service. It makes traces easier to filter and compare across environments.
        </Tip>
      </Step>

      <Step title="Initialize tracing early">
        Call `setup()` before constructing clients from instrumented SDKs.

        <CodeGroup>
          <Metadata text="get-started/capture-first-trace-manual-openai" />

          ```typescript TypeScript theme={"system"}
          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();
          ```

          <Metadata text="get-started/capture-first-trace-manual-openai" />

          ```python Python theme={"system"}
          import os

          from inference_catalyst_tracing import setup
          from openai import OpenAI

          tracing = setup()
          client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])

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

          print(response.choices[0].message.content)
          tracing.shutdown()
          ```
        </CodeGroup>

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

        <Tip>
          Longer-lived processes flush differently. A long-lived server (HTTP,
          Slack bot, queue worker) memoizes `setup()` and calls `shutdown()` on
          `SIGTERM`, not per request. A serverless or edge function instead
          flushes per invocation with `tracing.provider.forceFlush()`. See
          [Flushing and process lifecycle](/integrations/traces/quickstart#flushing-and-process-lifecycle)
          in the quickstart.
        </Tip>
      </Step>

      <Step title="View your trace">
        Open the [dashboard](https://inference.net/dashboard) and navigate to the Agents or Traces tab. You'll see an LLM span with input messages, output messages, model name, invocation parameters, finish reason, and token counts.
      </Step>
    </Steps>

    ### Group calls under an agent

    A single LLM call is captured automatically. To get an `AGENT` row with stable `agent.id`, `agent.name`, and `session.id` for dashboard grouping, wrap your code in `agentSpan`. Use `manualSpan` inside it for non-LLM steps like tools, retrieval, and validation. The example below reuses the `tracing` and `client` from the step above.

    <CodeGroup>
      <Metadata text="get-started/capture-first-trace-agent-typescript" />

      ```typescript TypeScript theme={"system"}
      import { agentSpan, manualSpan, SpanKindValues } from "@inference/tracing";

      await agentSpan(
        tracing.tracer,
        {
          agentId: "hello-agent",
          agentName: "Hello Agent",
          sessionId: "session-001",
        },
        async (span) => {
          const prompt = "Reply with just the word hello.";
          span.setInput(prompt);

          const response = await client.chat.completions.create({
            model: "gpt-4o-mini",
            messages: [{ role: "user", content: prompt }],
            max_tokens: 16,
          });
          const reply = response.choices[0]?.message.content ?? "";

          await manualSpan(
            tracing.tracer,
            { spanName: "validate_reply", spanKind: SpanKindValues.CHAIN, input: reply },
            async (step) => step.setOutput({ ok: reply.toLowerCase().includes("hello") }),
          );

          span.setOutput(reply);
        },
      );

      await tracing.shutdown();
      ```

      <Metadata text="get-started/capture-first-trace-agent-python" />

      ```python Python theme={"system"}
      from inference_catalyst_tracing import agent_span, manual_span, SpanKindValues

      prompt = "Reply with just the word hello."

      with agent_span(
          tracing.tracer,
          agent_id="hello-agent",
          agent_name="Hello Agent",
          session_id="session-001",
      ) as span:
          span.set_input(prompt)

          response = client.chat.completions.create(
              model="gpt-4o-mini",
              messages=[{"role": "user", "content": prompt}],
              max_tokens=16,
          )
          reply = response.choices[0].message.content or ""

          with manual_span(
              tracing.tracer,
              name="validate_reply",
              span_kind=SpanKindValues.CHAIN,
              input=reply,
          ) as step:
              step.set_output({"ok": "hello" in reply.lower()})

          span.set_output(reply)

      tracing.shutdown()
      ```
    </CodeGroup>

    The trace now shows an `AGENT` row for "Hello Agent" with the LLM call and the `validate_reply` `CHAIN` row nested under it. For the full surface (framework integrations, multi-agent setups, identity propagation), see the [tracing integrations guide](/integrations/traces/overview).

    <Note>
      Need a different provider or framework? See [Tracing integrations](/integrations/traces/overview) for OpenAI, Anthropic, LangChain, LangGraph, the Vercel AI SDK, Vercel Eve, OpenAI Agents, LiveKit, Claude Agent SDK, PI AI, Pydantic AI, and more.
    </Note>
  </Tab>
</Tabs>

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

<CardGroup cols={2}>
  <Card title="Analyze your traces" icon="microscope" href="/get-started/analyze-traces">
    Inspect trace trees in the dashboard and run Halo to find what to improve.
  </Card>

  <Card title="Add more integrations" icon="puzzle-piece" href="/integrations/traces/overview">
    Instrument Anthropic, LangChain, LangGraph, Vercel AI SDK, Vercel Eve, PI AI, agent frameworks, and more.
  </Card>

  <Card title="Set agent identity" icon="fingerprint" href="/integrations/traces/agent-identity">
    Add stable agent IDs so the Agents dashboard groups runs correctly.
  </Card>

  <Card title="Wrap custom work" icon="pen-nib" href="/integrations/traces/manual-spans">
    Add spans around your own orchestration, retrieval, and routing code.
  </Card>

  <Card title="Production agent example" icon="kitchen-set" href="/integrations/traces/production-agent-example">
    A production-shaped agent with custom tool spans, end to end.
  </Card>
</CardGroup>