Skip to main content

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.

Use manual spans for work that does not go through an instrumented SDK, such as CLI subprocess calls, custom LLM clients, tool execution, provider routing, or a high-level agent loop. Child spans created by instrumented SDKs inside the manual span are parented through OpenTelemetry context propagation. When the span represents an agent run, always include a stable agentId / agent_id plus the readable agent name. Catalyst uses agent.id first when grouping executions in the Agents dashboard.

​
Parent Span Around Automatic Child Spans

import { agentSpan, 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 });

await agentSpan(
  tracing.tracer,
  {
    agentId: "refund-review-agent",
    name: "RefundReviewAgent",
    role: "refunds",
    system: "openai",
  },
  async (span) => {
    const ticket = { id: "ticket_123", orderId: "ABC-123" };
    span.setInput(ticket);
    const response = await client.chat.completions.create({
      model: "gpt-4o-mini",
      messages: [
        { role: "user", content: `Review refund for ${ticket.orderId}` },
      ],
    });
    span.setOutput({ decision: response.choices[0]?.message.content });
    if (response.usage != null) {
      span.recordTokens({
        prompt: response.usage.prompt_tokens ?? 0,
        completion: response.usage.completion_tokens ?? 0,
      });
    }
  },
);

await tracing.shutdown();

​
CLI Or Subprocess Work

When a tool has no instrumentable SDK, wrap the process call and set input and output yourself.
TypeScript
import { agentSpan, setup } from "@inference/tracing";
import { execFile } from "node:child_process";
import { promisify } from "node:util";

const execFileP = promisify(execFile);
const tracing = await setup();
const prompt = "Reply with just the word hello.";

await agentSpan(
  tracing.tracer,
  {
    agentId: "claude-code-repo-worker",
    name: "ClaudeCode",
    system: "anthropic",
    spanName: "claude-code.invocation",
  },
  async (span) => {
    span.setInput(prompt);
    const { stdout } = await execFileP("claude", ["-p", prompt], {
      encoding: "utf-8",
      timeout: 60_000,
    });
    span.setOutput(stdout.trim());
  },
);

await tracing.shutdown();

​
Custom Span Kind

Use manual_span() in Python when the operation should be a CHAIN, TOOL, RETRIEVER, or another OpenInference span kind.
Python
from inference_catalyst_tracing import SpanKindValues, manual_span, setup

tracing = setup()

with manual_span(
    tracing.tracer,
    name="provider_router/select_model",
    span_kind=SpanKindValues.CHAIN,
    system="internal",
    input={"route": "support", "priority": "high"},
    metadata={"customer_tier": "enterprise"},
    tags=["router", "support"],
) as span:
    selected = choose_model_for_request()
    span.set_output({"model": selected.model, "reason": selected.reason})

tracing.shutdown()