opik

Opik SDK Reference

Opik is an open-source LLM observability platform. This skill is a reference for the SDK. To instrument a codebase step by step (detect frameworks, add config, emit and verify a trace), use the task-shaped opik-instrument skill.

Core concepts

A trace is one execution path (one request → one response). Spans are the operations inside it and form a hierarchy.

Span types — the ONLY valid values

Type	Use for
general	orchestration, agent entry points
llm	model calls
tool	tools, retrieval, API / DB calls
guardrail	safety / validation checks

Do NOT use retrieval or any other value.

Python — tracing

import opik

@opik.track(name="agent", type="general")
def agent(query: str) -> str:
    return generate(retrieve(query))

@opik.track(type="tool")
def retrieve(query): ...

@opik.track(type="llm")
def generate(ctx): ...

opik.flush_tracker()   # required in scripts

TypeScript — tracing

import { Opik } from "opik";
const client = new Opik({ projectName: "my-project" });

const trace = client.trace({ name: "agent", input: { query } });
const span = trace.span({ name: "llm-call", type: "llm" });
span.end({ output });
trace.end({ output });
await client.flush();

Framework integrations

Prefer an integration over manual @opik.track — integrations capture tokens, model, and cost automatically. Patterns (full list in references/integrations.md):

• wrap-the-client — track_openai(OpenAI()), track_anthropic(...)
• global-enable — track_crewai(crew=crew)
• callback — dspy.configure(callbacks=[OpikCallback()])
• tracer — OpikTracer() for LangChain / LangGraph / LlamaIndex
• agent-specific — track_adk_agent_recursive(agent, OpikTracer())

LiteLLM inside @opik.track (common trap)

If code uses litellm and you add @opik.track, pass current_span_data via metadata on every completion call — otherwise OpikLogger emits orphaned top-level traces instead of nesting under your span.