Traces Quickstart

This page is the SDK-focused quickstart: install the @inference/tracing (TypeScript) or inference-tracing (Python) package, point it at the Inference platform, and capture your first span. If you'd rather see the higher-level flow, start with Capture your first trace.

The example below uses OpenAI because it's the smallest end-to-end trace. The same export configuration applies to Anthropic, LangChain, LangGraph, LangSmith, OpenAI Agents, LiveKit Agents, ElevenLabs Agents, Vercel Eve, Pi Agent, legacy PI AI, Cursor SDK, Claude Agent SDK, Pydantic AI, the Vercel AI SDK, and manual spans. Each framework guide shows the exact setup hook for that SDK.

Choose a setup path

Installing with AI is the quickest. Use the manual flow if you want to wire it up yourself.

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

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

export INFERENCE_OTLP_ENDPOINT="https://telemetry.inference.net"
# Get your API key from https://inference.net/dashboard/api-keys/
export INFERENCE_API_KEY="<your-token>"
export INFERENCE_SERVICE_NAME="checkout-agent"

That's it. Spans are streaming to the Inference platform and your first trace is ready to inspect.

What you have so far is one LLM span per call, captured automatically. That's enough for a one-shot script, but real apps usually run several calls per user request, and you'll want those grouped under a named agent and session in the dashboard. That's the next step. If you used Install with AI, the agent likely already wired this up for you; read on to see what it set up and why.

Group calls under an agent

The example above is a one-shot LLM call. Once your app runs multiple LLM calls as part of a logical unit (an agent run, a conversation turn, a workflow), wrap that unit in agentSpan so the LLM spans nest under an AGENT row carrying agent.id, agent.name, and session.id. The Agents dashboard groups on those attributes.

The OpenAI LLM span still appears, but now nested under your agentSpan row instead of as an orphan. Real agents run many LLM calls per session; the outer span is what makes them findable as one thing.

Wrap your own code

For non-LLM steps inside an agent loop (a tool call, a retrieval, a custom router, an evaluator, a CLI subprocess), wrap them with manualSpan. Combined with the agentSpan above, you get a full trace tree: an outer AGENT row, inner SDK rows, and inner manual rows, all parented correctly.

For the full manual-span surface (tools, retrievers, embeddings, agent identity), see Manual spans and Agent identity.

Flushing and process lifecycle

Spans are batched and exported in the background, so a process that exits or freezes before the batch flushes drops them. How you flush depends on the process shape:

• Short-lived script: call await tracing.shutdown() before exit. It force-flushes, then tears the provider down. The examples above do this.
• Long-lived service (HTTP server, Slack bot, queue worker): call setup() once per process before the first SDK client is constructed, memoize the result so any handler can await it, and call shutdown() only on SIGTERM. Never per request, since that forces a synchronous flush and adds latency.
• Serverless or edge (Lambda, Cloudflare Workers): memoize setup() the same way, but flush per invocation with tracing.provider.forceFlush() instead of shutdown(), since the provider must survive for the next warm invocation.

Long-lived service

Serverless and edge runtimes

On Lambda, Cloudflare Workers, or any runtime that freezes the process between invocations, the background batch processor may never run, so spans are dropped. Memoize setup() the same way as a long-lived service (the provider is reused across warm invocations), but flush at the end of each invocation with tracing.provider.forceFlush() rather than calling shutdown(). Reserve shutdown() for real process teardown, since it tears down the provider the next warm invocation needs.

Selective instrumentation

setup() auto-instruments every supported SDK it detects. If you want explicit control — for example, to instrument OpenAI but skip LangChain — set autoInstrument: false and call the targeted helper yourself:

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

const tracing = await setup({ autoInstrument: false });
instrumentOpenAI(OpenAI, tracing);

The per-integration entry points are listed in the overview's configuration section.

For a full production-shaped server with custom tool spans and domain attributes, see the Production Agent Example.

Verify

Open the Inference.net dashboard and navigate to the Agents or Traces tab. The trace should include an OpenAI LLM span with input messages, output messages, model name, invocation parameters, finish reason, and token counts. Any custom spans you added show up as parent or sibling nodes in the trace tree.

If you don't see anything, see Troubleshooting.

Next Steps