OpenTelemetry

Opik provides native support for OpenTelemetry (OTel), allowing you to instrument your ML/AI applications with distributed tracing. This guide will show you how to directly integrate OpenTelemetry SDKs with Opik.

OpenTelemetry Endpoint Configuration

Base Endpoint

To start sending traces to Opik, configure your OpenTelemetry exporter with one of these endpoints:

export OTEL_EXPORTER_OTLP_ENDPOINT="https://www.comet.com/opik/api/v1/private/otel"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=<your-api-key>,projectName=<your-project-name>,Comet-Workspace=<your-workspace-name>"

Signal-Specific Endpoint

If your OpenTelemetry setup requires signal-specific configuration, you can use the traces endpoint. This is particularly useful when different signals (traces, metrics, logs) need to be sent to different endpoints:

export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="http://<YOUR-OPIK-INSTANCE>/api/v1/private/otel/v1/traces"

Custom via OpenTelemetry SDKs

You can use any OpenTelemetry SDK to send traces directly to Opik. OpenTelemetry provides SDKs for many languages (C++, .NET, Erlang/Elixir, Go, Java, JavaScript, PHP, Python, Ruby, Rust, Swift). This extends Opik’s language support beyond the official SDKs (Python and TypeScript). For more instructions, visit the OpenTelemetry documentation.

Here’s a Python example showing how to set up OpenTelemetry with Opik:

from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.http.trace_exporter import (
    OTLPSpanExporter
)
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
# For Comet-hosted installations
OPIK_ENDPOINT = "https://<COMET-SERVER>/api/v1/private/otel/v1/traces"
API_KEY = "<your-api-key>"
PROJECT_NAME = "<your-project-name>"
WORKSPACE_NAME = "<your-workspace-name>"
# Initialize the trace provider
provider = TracerProvider()
processor = BatchSpanProcessor(
    OTLPSpanExporter(
        endpoint=OPIK_ENDPOINT,
        headers={
            "Authorization": API_KEY,
            "projectName": PROJECT_NAME,
            "Comet-Workspace": WORKSPACE_NAME
        }
    )
)
provider.add_span_processor(processor)
trace.set_tracer_provider(provider)

pip install opentelemetry-instrumentation-openai

from opentelemetry.instrumentation.openai import OpenAIInstrumentor
OpenAIInstrumentor().instrument()

How Opik builds traces from spans

OpenTelemetry sends spans only. Opik creates a trace from the root span of each OpenTelemetry trace: the span that has no parent span. The name, input, output, metadata, tags and errors of the root span become the values of the trace.

Opik treats a span as a root span when one of these conditions is true:

• The parentSpanId of the span is empty.
• The parentSpanId of the span is equal to its traceId.

Supported attribute conventions

Opik reads the attributes of each span and maps them to the fields of the Opik span. Opik supports the OpenTelemetry GenAI semantic conventions, the OpenInference conventions and a set of general Opik attributes. Opik also reads the attributes of some framework instrumentations, such as Logfire, Pydantic AI, LiteLLM, smolagents, LiveKit and Langfuse.

Some other rules apply:

• A more specific attribute has priority over a prefix. For example, gen_ai.request.model sets the model, and the other gen_ai.request.* attributes go to the input.
• Opik renames the input_tokens and output_tokens usage keys to prompt_tokens and completion_tokens. If the span has no total_tokens, Opik calculates it.
• Opik sets the span type to llm when the span has a GenAI or OpenInference model or token usage attribute. Opik sets the span type to tool when the span has gen_ai.tool.call.arguments or gen_ai.tool.call.result.
• When the value of input, output or opik.metadata is a JSON object in a string, Opik adds the keys of the object to the field.
• Opik adds the span events to the metadata of the span. An exception event, or a span status of ERROR, becomes the error of the span.

Opik-specific span attributes

Opik reads a small set of span attributes and maps them to Opik fields. Set them with the standard OpenTelemetry API on any span.

Tagging traces and spans

Opik accepts three formats for the opik.tags attribute:

• A list of strings: ["production", "chatbot"]
• A JSON array in a string: '["production", "chatbot"]'
• A comma-separated string: "production,chatbot"

with tracer.start_as_current_span("chatbot_conversation") as conversation_span:
    # The root span carries the tags, so the trace carries them too
    conversation_span.set_attribute("opik.tags", ["production", "chatbot"])
    conversation_span.set_attribute("opik.metadata.environment", "staging")
    with tracer.start_as_current_span("llm_completion") as llm_span:
        # A child span carries the tags on the span only
        llm_span.set_attribute("opik.tags", ["llm-call"])

Routing spans to a project

Some OpenTelemetry Collector processors, such as tail_sampling, do not forward the HTTP headers of the incoming request. In that case, set the project with the opik.project_name attribute instead of the projectName header.

Opik picks the project of each span on its own, in this order:

1. The opik.project_name attribute of the span
2. The opik.project_name attribute of the resource of the span
3. The projectName header
4. The Default Project

Opik ignores a value longer than 150 characters.

Set the project on every span

A resource attribute applies to every span that the process sends. Use one of these methods:

export OTEL_RESOURCE_ATTRIBUTES="opik.project_name=<your-project-name>"

Send spans to Opik and to other backends

One OpenTelemetry TracerProvider can send each span to more than one backend. Add one BatchSpanProcessor for each exporter. The frameworks that use OpenTelemetry (such as Strands Agents, LangGraph, LlamaIndex and CrewAI) send their spans to the global tracer provider, so one setup covers all of them.

from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
provider = TracerProvider()
# Opik
provider.add_span_processor(
    BatchSpanProcessor(
        OTLPSpanExporter(
            endpoint="https://www.comet.com/opik/api/v1/private/otel/v1/traces",
            headers={
                "Authorization": "<your-api-key>",
                "Comet-Workspace": "<your-workspace-name>",
                "projectName": "<your-project-name>",
            },
        )
    )
)
# Other backend
provider.add_span_processor(
    BatchSpanProcessor(OTLPSpanExporter(endpoint="https://<other-backend>/v1/traces"))
)
trace.set_tracer_provider(provider)

When the platform continues an incoming trace, the first span of your agent has a parent. In this case, add a root span for each invocation, as shown in Troubleshooting.

Troubleshooting

import json
from opentelemetry import trace
from opentelemetry.context import Context
from opentelemetry.trace import Link
tracer = trace.get_tracer("my-agent")
def invoke(payload: dict) -> str:
    # Keep a link to the incoming trace, so that other backends can still connect the two traces
    incoming = trace.get_current_span().get_span_context()
    links = [Link(incoming)] if incoming.is_valid else []
    with tracer.start_as_current_span("agent_invocation", context=Context(), links=links) as root_span:
        root_span.set_attribute("input.value", json.dumps(payload))
        result = str(agent(payload["prompt"]))
        root_span.set_attribute("output.value", result)
        return result