Instrument — Add Opik Tracing to a Codebase

Step 1 — Scope

$ARGUMENTS

Step 2 — Detect Language & Frameworks

1. Language: Python (look for

   *.py

   ,

   pyproject.toml

   ,

   requirements.txt

   ) or TypeScript (look for

   *.ts

   ,

   *.tsx

   ,

   package.json

   )
2. LLM frameworks in use — search imports for these patterns:

from openai

import OpenAI

track_openai

import anthropic

track_anthropic

from langchain

@langchain

OpikTracer

from langgraph

OpikTracer

graph=

from crewai

track_crewai

import dspy

OpikCallback

from google

genai

track_genai

import boto3

bedrock

track_bedrock

from llama_index

LlamaIndexCallbackHandler

import litellm

OpikLogger

from pydantic_ai

from opik.integrations.adk

from google.adk

track_adk_agent_recursive

import ollama

track_openai

@opik.track

from agents import

from openai.agents

OpikTracingProcessor

from haystack

OpikConnector

opik-openai

trackOpenAI

trackOpenAI

opik-vercel

OpikExporter

OpikExporter

opik-langchain

OpikCallbackHandler

OpikCallbackHandler

opik-gemini

trackGemini

trackGemini

1. Existing Opik usage — check if

   opik

   or

   @opik.track

   is already imported. If so, audit rather than re-instrument.

Step 3 — Identify the Call Graph

• Entrypoint: the top-level function that kicks off the agent (e.g.,

  main

  ,

  run

  ,

  agent

  ,

  handle_message

  , a route handler, or whatever the user's main orchestration function is)
• LLM call sites: functions that call an LLM provider directly
• Tool functions: retrieval, search, API calls, or other tool-like operations
• Existing config classes: dataclasses, Pydantic models, or plain classes holding model names, temperatures, prompts, or other tunable parameters

Step 4 — Add Framework Integrations

references/integrations.md

# OpenAI
from opik.integrations.openai import track_openai
client = track_openai(OpenAI())  # wrap existing client

# Anthropic
from opik.integrations.anthropic import track_anthropic
client = track_anthropic(anthropic.Anthropic())

# LangChain / LangGraph
from opik.integrations.langchain import OpikTracer
tracer = OpikTracer()
# pass config={"callbacks": [tracer]} to invoke()

# LiteLLM inside @opik.track — CRITICAL: pass span context
from opik.opik_context import get_current_span_data
# in every litellm.completion() call, add:
#   metadata={"opik": {"current_span_data": get_current_span_data()}}

// OpenAI
import { trackOpenAI } from "opik-openai";
const trackedClient = trackOpenAI(openai);

// Vercel AI SDK
import { OpikExporter } from "opik-vercel";
// set up NodeSDK with OpikExporter

Step 5 — Add

@opik.track

Decorators (Python) or Client Tracing (TypeScript)

Python

import opik

@opik.track(entrypoint=True, name="<agent-name>")

@opik.track(type="llm")

@opik.track(type="tool")

@opik.track(type="guardrail")

@opik.track

• Place the decorator above any existing decorators (e.g., above

  @app.route

  )
• For async functions,

  @opik.track

  works the same way — no changes needed
• If the function is a script entrypoint (not a long-running server), add

  opik.flush_tracker()

  after the top-level call

TypeScript

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

// In the entrypoint function:
const trace = client.trace({ name: "<agent-name>", input: { ... } });
const span = trace.span({ name: "<operation>", type: "tool", input: { ... } });
// ... logic
span.end({ output: { ... } });
trace.end({ output: { ... } });
await client.flush();

opik connect

import { track } from "opik";

const myAgent = track(
  { name: "<agent-name>", entrypoint: true, params: [{ name: "query", type: "string" }] },
  async (query: string) => { /* ... */ }
);

Step 6 — Conversational Agents: Add

thread_id

thread_id

@opik.track(entrypoint=True)
def handle_message(session_id: str, message: str) -> str:
    opik.update_current_trace(thread_id=session_id)
    return generate_response(session_id, message)

Step 7 — Environment Config

1. If the project has

   .env

   /

   .env.local

   → append

   OPIK_API_KEY

   ,

   OPIK_WORKSPACE

   ,

   OPIK_URL_OVERRIDE

   (if missing)
2. If no

   .env

   exists → Python: create/update

   ~/.opik.config

   ; TypeScript: create

   .env

   or

   .env.local

3. Never introduce a second config mechanism
4. Never overwrite existing values
5. Update

   .env.example

   /

   .env.sample

   if one exists
6. Set

   project_name

   in code, not in env files

Step 8 — Install Dependencies

pip install opik

opik

npm install opik

opik-openai

opik-vercel

opik-langchain

opik-gemini

Step 9 — Verify

• Every LLM call site is traced (via integration wrapper or

  @opik.track

  )
• Exactly one function has

  entrypoint=True

• Script entrypoints call

  opik.flush_tracker()

  (Python) or

  await client.flush()

  (TypeScript)
• LiteLLM calls inside

  @opik.track

  pass

  current_span_data

  via metadata
• No hardcoded API keys were introduced
• Existing tests still import correctly (no circular imports introduced)

Anti-Patterns to Avoid

• Double-wrapping: Don't add

  @opik.track(type="llm")

  to a function that already uses a framework integration (e.g.,

  track_openai

  ). The integration handles tracing.
• Orphaned LiteLLM traces: Always pass

  current_span_data

  when

  OpikLogger

  is used inside

  @opik.track

  code.
• Missing entrypoint: Without

  entrypoint=True

  , Local Runner (

  opik connect

  ) won't discover the agent.
• Missing flush: Scripts that exit without flushing lose trace data.
• Overwriting config: Check before writing to

  .env

  or

  ~/.opik.config

  .

References

• ../opik/references/tracing-python.md

  — Python SDK reference

• ../opik/references/tracing-typescript.md

  — TypeScript SDK reference

• ../opik/references/integrations.md

  — All 40+ framework integrations

• ../opik/references/observability.md

  — Core concepts (traces, spans, threads)