opik

name	opik
description	This skill should be used when the user needs to add Opik tracing or integrations to their code, instrument an LLM application, or needs reference for Opik SDK usage (Python, TypeScript, REST API). Use for tasks like "add tracing", "instrument my code", "use track_openai", "add OpikTracer", "what span types are available", "how to flush traces".

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