> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://www.comet.com/docs/opik/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://www.comet.com/docs/opik/_mcp/server.

# OpenTelemetry

# Get Started with 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 integration in Opik currently supports HTTP transport. We're actively working on expanding the feature
set - stay tuned for updates!

## OpenTelemetry Endpoint Configuration

### Base Endpoint

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

#### Opik Cloud

```bash wordWrap
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>"
```

#### Self-hosted deployment

```bash wordWrap
export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:5173/api/v1/private/otel"
```

#### Enterprise deployment

```bash wordWrap
export OTEL_EXPORTER_OTLP_ENDPOINT="https://<comet deployment url>/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:

```bash wordWrap
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](https://opentelemetry.io/docs/languages/).

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

```python wordWrap
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)
```

In order to track OpenAI calls, you need to use the OpenTelemetry instrumentations
for OpenAI:

```bash wordWrap
pip install opentelemetry-instrumentation-openai
```

And then instrument your OpenAI client:

```python wordWrap
from opentelemetry.instrumentation.openai import OpenAIInstrumentor

OpenAIInstrumentor().instrument()
```

Make sure to import the `http` trace exporter (`opentelemetry.exporter.otlp.proto.http.trace_exporter`), if you use
the GRPC exporter you will face errors.

## 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.

| Attribute                                              | Effect                                                                                                                                     |
| ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `opik.tags`                                            | Adds tags to the span. On the root span, Opik also adds the tags to the trace, so you can filter your traces by tag.                       |
| `opik.metadata.<key>`                                  | Adds `<key>` to the metadata of the span. The metadata of the root span also becomes the metadata of the trace.                            |
| `thread_id`                                            | Groups traces into one conversational thread. See [Multi-turn conversations](/evaluation/evaluate_threads).                                |
| `opik.trace_id`, `opik.parent_span_id`, `opik.span_id` | Attaches the span to an Opik trace and parent span that already exist. See [Distributed traces](/tracing/advanced/log_distributed_traces). |

### 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"`

```python wordWrap
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"])
```

Set `opik.tags` on the root span if you want to filter traces by tag. Tags on a child span apply to that span only.