Opik

Opik SDK Reference

Opik is an open-source LLM observability platform. This skill covers the SDK: tracing, integrations, span types, and how to instrument code.

Core Concepts

Traces and Spans

A trace is a complete execution path (one user request → one response). Spans are individual operations within a trace, forming a hierarchy.

Span Types

| Type | Use For | Example | |------|---------|---------| | general | Custom operations, orchestration | Data processing, agent entry point | | llm | LLM API calls | OpenAI completion, Anthropic message | | tool | Tool/function execution, data retrieval | Web search, vector DB query, calculator | | guardrail | Safety/validation checks | PII detection, content moderation |

These are the ONLY valid span types. Do NOT use retrieval or any other type.

Python Quick Start

import opik

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

@opik.track(type="tool")
def retrieve(query: str) -> list:
    return search_db(query)

@opik.track(type="llm")
def generate(query: str, context: list) -> str:
    return llm_call(query, context)

# Nested calls automatically create child spans
result = agent("What is ML?")
opik.flush_tracker()  # Flush for scripts

TypeScript Quick Start

import { Opik } from "opik";

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

const trace = client.trace({ name: "my-agent", input: { query: "Hello" } });
const span = trace.span({ name: "llm-call", type: "llm" });
// ... LLM call
span.end({ output: { response: "Hi!" } });
trace.end({ output: { response: "Hi!" } });

await client.flush();

Framework Integrations

Use framework-specific integrations instead of manual @opik.track when available — they capture more detail (tokens, model, cost) automatically.

For the full list of integrations with code snippets, see references/integrations.md.

Common Patterns

Wrap-the-client (OpenAI, Anthropic, Bedrock, Gemini, etc.):

from opik.integrations.openai import track_openai
client = track_openai(OpenAI())
# All calls now traced automatically

Global enable (CrewAI, DSPy, etc.):

from opik.integrations.crewai import track_crewai
track_crewai(project_name="my-project", crew=crew)  # crew= required for v1.0.0+

Callback-based (DSPy):

from opik.integrations.dspy import OpikCallback
dspy.configure(callbacks=[OpikCallback()])

Callback/tracer (LangChain, LangGraph, LlamaIndex):

from opik.integrations.langchain import OpikTracer
tracer = OpikTracer()
result = chain.invoke(input, config={"callbacks": [tracer]})

Agent-specific (Google ADK):

from opik.integrations.adk import OpikTracer, track_adk_agent_recursive
opik_tracer = OpikTracer()
track_adk_agent_recursive(agent, opik_tracer)

Detailed References

| Topic | Reference File | |-----------------------------------------------------------------------------|----------------| | Python SDK (decorators, context, async, distributed tracing, configuration) | references/tracing-python.md | | TypeScript SDK (client, decorators, framework integrations) | references/tracing-typescript.md | | REST API (HTTP endpoints, authentication) | references/tracing-rest-api.md | | All integrations with code snippets | references/integrations.md | | Core concepts (traces, spans, threads, metadata, feedback) | references/observability.md |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: comet-ml
• Source: comet-ml/opik-claude-code-plugin
• License: Apache-2.0
• Homepage: https://www.comet.com/site/products/opik/

Install and usage instructions live in the source repository linked above.