Log traces | Opik Documentation | Opik Documentation

If you are just getting started with Opik, we recommend first checking out the Quickstart guide that will walk you through the process of logging your first LLM call.

LLM applications are complex systems that do more than just call an LLM API, they will often involve retrieval, pre-processing and post-processing steps. Tracing is a tool that helps you understand the flow of your application and identify specific points in your application that may be causing issues.

Opik’s tracing functionality allows you to track not just all the LLM calls made by your application but also any of the other steps involved.

Opik supports agent observability using our Typescript SDK, Python SDK, first class OpenTelemetry support, and our REST API.

We recommend starting with one of our integrations to get started quickly, you can find a full list of our integrations in the integrations overview page.

We won’t be covering how to track chat conversations in this guide, you can learn more about this in the Logging conversations guide.

Enable agent observability

1. Installing the SDK

Before adding observability to your application, you will first need to install and configure the Opik SDK.

Typescript SDK
Python SDK
OpenTelemetry
npm install opik

You can then set the Opik environment variables in your .env file:

# Set OPIK_API_KEY and OPIK_WORKSPACE in your .env file
OPIK_API_KEY=your_api_key_here
OPIK_WORKSPACE=your_workspace_name

# Optional if you are using Opik Cloud:
OPIK_URL_OVERRIDE=https://www.comet.com/opik/api

Opik is open-source and can be hosted locally using Docker, please refer to the self-hosting guide to get started. Alternatively, you can use our hosted platform by creating an account on Comet.

2. Using an integration

Once you have installed and configured the Opik SDK, you can start using it to track your agent calls:

OpenAI (TS)
OpenAI (Python)
AI Vercel SDK
ADK
LangGraph
Function Decorators
AI Wizard
Other

If you are using the OpenAI TypeScript SDK, you can integrate by:

1

Install the Opik TypeScript SDK:

npm install opik-openai

2

Configure the Opik TypeScript SDK using environment variables:

export OPIK_API_KEY="<your-api-key>" # Only required if you are using the Opik Cloud version
export OPIK_URL_OVERRIDE="https://www.comet.com/opik/api" # Cloud version
# export OPIK_URL_OVERRIDE="http://localhost:5173/api" # Self-hosting

3

Wrap your OpenAI client with the trackOpenAI function:

import OpenAI from "openai";
import { trackOpenAI } from "opik-openai";

// Initialize the original OpenAI client
const openai = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
});

// Wrap the client with Opik tracking
const trackedOpenAI = trackOpenAI(openai);

// Use the tracked client just like the original
const completion = await trackedOpenAI.chat.completions.create({
  model: "gpt-4",
  messages: [{ role: "user", content: "Hello, how can you help me today?" }],
});
console.log(completion.choices[0].message.content);

// Ensure all traces are sent before your app terminates
await trackedOpenAI.flush();

All OpenAI calls made using the trackedOpenAI will now be logged to Opik.

Opik has more than 40 integrations with the majority of the popular frameworks and libraries. You can find a full list of integrations in the integrations overview page.

If you would like more control over the logging process, you can use the low-level SDKs to log your traces and spans.

3. Analyzing your agents

Now that you have observability enabled for your agents, you can start to review and analyze the agent calls in Opik. In the Opik UI, you can review each agent call, see the agent graph and review all the tool calls made by the agent.

Advanced usage

Using function decorators

Function decorators are a great way to add Opik logging to your existing application. When you add the @track decorator to a function, Opik will create a span for that function call and log the input parameters and function output for that function. If we detect that a decorated function is being called within another decorated function, we will create a nested span for the inner function.

While decorators are most popular in Python, we also support them in our Typescript SDK:

Typescript
Python

TypeScript started supporting decorators from version 5 but it’s use is still not widespread. The Opik typescript SDK also supports decorators but it’s currently considered experimental.

import { track } from "opik";

class TranslationService {
    @track({ type: "llm" })
    async generateText() {
        // Your LLM call here
        return "Generated text";
    }

@track({ name: "translate" })
    async translate(text: string) {
        // Your translation logic here
        return `Translated: ${text}`;
    }

@track({ name: "process", projectName: "translation-service" })
    async process() {
        const text = await this.generateText();
        return this.translate(text);
    }
}

You can also specify custom tags, metadata, and/or a thread_id for each trace and/or span logged for the decorated function. For more information, see Logging additional data using the opik_args parameter

Using the low-level SDKs

If you need full control over the logging process, you can use the low-level SDKs to log your traces and spans:

Typescript
Python

You can use the Opik client to log your traces and spans:

import { Opik } from "opik";

const client = new Opik({
    apiUrl: "https://www.comet.com/opik/api",
    apiKey: "your-api-key", // Only required if you are using Opik Cloud
    projectName: "your-project-name",
    workspaceName: "your-workspace-name", // Optional
});

// Log a trace with an LLM span
const trace = client.trace({
    name: `Trace`,
    input: {
        prompt: `Hello!`,
    },
    output: {
        response: `Hello, world!`,
    },
});

const span = trace.span({
    name: `Span`,
    type: "llm",
    input: {
        prompt: `Hello, world!`,
    },
    output: {
        response: `Hello, world!`,
    },
});

// Flush the client to send all traces and spans
await client.flush();

Make sure you define the environment variables for the Opik client in your .env file, you can find more information about the configuration here.

Logging traces/spans using context managers

If you are using the low-level SDKs, you can use the context managers to log traces and spans. Context managers provide a clean and Pythonic way to manage the lifecycle of traces and spans, ensuring proper cleanup and error handling.

Python

Opik provides two main context managers for logging:

opik.start_as_current_trace()

Use this context manager to create and manage a trace. A trace represents the overall execution flow of your application.

For detailed API reference, see opik.start_as_current_trace.

import opik

# Basic trace creation
with opik.start_as_current_trace("my-trace", project_name="my-project") as trace:
    # Your application logic here
    trace.input = {"user_query": "What is the weather?"}
    trace.output = {"response": "It's sunny today!"}
    trace.tags = ["weather", "api-call"]
    trace.metadata = {"model": "gpt-4", "temperature": 0.7}

Parameters:

opik.start_as_current_span()

Use this context manager to create and manage a span within a trace. Spans represent individual operations or function calls.

For detailed API reference, see opik.start_as_current_span.

import opik

# Basic span creation
with opik.start_as_current_span("llm-call", type="llm", project_name="my-project") as span:
    # Your LLM call here
    span.input = {"prompt": "Explain quantum computing"}
    span.output = {"response": "Quantum computing is..."}
    span.model = "gpt-4"
    span.provider = "openai"
    span.usage = {
        "prompt_tokens": 10,
        "completion_tokens": 50,
        "total_tokens": 60
    }

Parameters:

Nested Context Managers

You can nest spans within traces to create hierarchical structures:

import opik

with opik.start_as_current_trace("chatbot-conversation", project_name="chatbot") as trace:
    trace.input = {"user_message": "Help me with Python"}

# First span: Process user input
    with opik.start_as_current_span("process-input", type="general") as span:
        span.input = {"raw_input": "Help me with Python"}
        span.output = {"processed_input": "Python programming help request"}

# Second span: Generate response
    with opik.start_as_current_span("generate-response", type="llm") as span:
        span.input = {"prompt": "Python programming help request"}
        span.output = {"response": "I'd be happy to help with Python!"}
        span.model = "gpt-4"
        span.provider = "openai"

trace.output = {"final_response": "I'd be happy to help with Python!"}

Error Handling

Context managers automatically handle errors and ensure proper cleanup:

import opik

try:
    with opik.start_as_current_trace("risky-operation", project_name="my-project") as trace:
        trace.input = {"data": "important data"}
        # This will raise an exception
        result = 1 / 0
        trace.output = {"result": result}
except ZeroDivisionError:
    # The trace is still properly closed and logged
    print("Error occurred, but trace was logged")

Dynamic Parameter Updates

You can modify trace and span parameters both inside and outside the context manager:

import opik

# Parameters set outside the context manager
with opik.start_as_current_trace(
    "dynamic-trace",
    input={"initial": "data"},
    tags=["initial-tag"],
    project_name="my-project"
) as trace:
    # Override parameters inside the context manager
    trace.input = {"updated": "data"}
    trace.tags = ["updated-tag", "new-tag"]
    trace.metadata = {"custom": "metadata"}

# The final trace will use the updated values

Flush Control

Control when data is sent to Opik:

import opik

# Immediate flush
with opik.start_as_current_trace("immediate-trace", flush=True) as trace:
    trace.input = {"data": "important"}
    # Data is sent immediately when exiting the context

# Deferred flush (default)
with opik.start_as_current_trace("deferred-trace", flush=False) as trace:
    trace.input = {"data": "less urgent"}
    # Data will be sent asynchronously later or when the program exits

Best Practices

  1. Use descriptive names: Choose clear, descriptive names for your traces and spans that explain what they represent.
  2. Set appropriate types: Use the correct span types (“llm”, “retrieval”, “general”, etc.) to help with filtering and analysis.
  3. Include relevant metadata: Add metadata that will be useful for debugging and analysis, such as model names, parameters, and custom metrics.
  4. Handle errors gracefully: Let the context manager handle cleanup, but ensure your application logic handles errors appropriately.
  5. Use project organization: Organize your traces by project to keep your Opik dashboard clean and organized.
  6. Consider performance: Use flush=True only when immediate data availability is required, as it can slow down your application by triggering a synchronous, immediate data upload.

Logging to a specific project

By default, traces are logged to the Default Project project. You can change the project you want the trace to be logged to in a couple of ways:

Typescript
Python

You can use the OPIK_PROJECT_NAME environment variable to set the project you want the trace to be logged or pass a parameter to the Opik client.

import { Opik } from "opik";

const client = new Opik({
    projectName: "my_project",
    // apiKey: "my_api_key",
    // apiUrl: "https://www.comet.com/opik/api",
    // workspaceName: "my_workspace",
});

Project name resolution (Python SDK)

The project name is determined differently depending on whether an active project context already exists.

When no project context is active

This applies to the top-level@track-decorated function call, the Opik() client, or a native integration (e.g., track_openai, OpikTracer) used outside any traced context. The project name is resolved in this order:

  1. Explicit project_name argument — passed directly to @track(project_name="..."), Opik(project_name="..."), OpikTracer(project_name="..."), or a client method like client.trace(project_name="...")
  2. Client configuration — from the OPIK_PROJECT_NAME environment variable or ~/.opik.config file
  3. Default — falls back to `