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

# OpenTelemetry (tracing)

[OpenTelemetry (OTel)](https://opentelemetry.io/) is the CNCF standard for distributed tracing. If your application already uses OTel, you can send traces directly to Respan without installing any Respan SDK — just point your OTLP exporter at Respan's endpoint.

Respan accepts traces via the standard [OTLP/HTTP](https://opentelemetry.io/docs/specs/otlp/) protocol in both **JSON** and **Protobuf** formats at `/api/v2/traces`.

## Why use OpenTelemetry with Respan?

* **Zero vendor lock-in** — Use standard OTel instrumentation, switch backends anytime
* **Works with existing instrumentation** — Any OTel-compatible library (Traceloop, OpenInference, OpenLIT, custom) sends to Respan
* **Full semantic convention support** — GenAI, Traceloop, and OpenInference attributes are automatically mapped to Respan fields
* **Combine sources** — Mix OTel traces with Respan SDK traces in the same dashboard

## Quickstart

### Option 1: Environment variables

The simplest setup — works with any OTel SDK or instrumentation library.

```bash
export OTEL_EXPORTER_OTLP_ENDPOINT="https://api.respan.ai/api"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer YOUR_RESPAN_API_KEY"
export OTEL_EXPORTER_OTLP_PROTOCOL="http/json"
```

Then run your application as usual. Any OTel-instrumented code exports traces to Respan automatically.

### Option 2: Direct SDK configuration

#### Python

```bash
pip install opentelemetry-sdk opentelemetry-exporter-otlp-proto-http
```

```python
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter

exporter = OTLPSpanExporter(
    endpoint="https://api.respan.ai/api/v2/traces",
    headers={"Authorization": "Bearer YOUR_RESPAN_API_KEY"},
)

provider = TracerProvider()
provider.add_span_processor(BatchSpanProcessor(exporter))
trace.set_tracer_provider(provider)

tracer = trace.get_tracer(__name__)

with tracer.start_as_current_span("my-llm-call") as span:
    span.set_attribute("gen_ai.request.model", "gpt-4o")
    span.set_attribute("gen_ai.usage.prompt_tokens", 150)
    span.set_attribute("gen_ai.usage.completion_tokens", 50)
    # your LLM call here
```

#### TypeScript

```bash
npm install @opentelemetry/sdk-node @opentelemetry/exporter-trace-otlp-http
```

```typescript
import { NodeSDK } from "@opentelemetry/sdk-node";
import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";

const sdk = new NodeSDK({
  traceExporter: new OTLPTraceExporter({
    url: "https://api.respan.ai/api/v2/traces",
    headers: {
      Authorization: "Bearer YOUR_RESPAN_API_KEY",
    },
  }),
});

sdk.start();
```

### Option 3: OpenTelemetry Collector

Route traces through an [OTel Collector](https://opentelemetry.io/docs/collector/) to Respan. Useful when you want to fan out to multiple backends or apply processing. For at-least-once delivery across outages and restarts (persistent, bounded queue), use the packaged Respan Collector (`respan collector start`, see the [CLI](/docs/documentation/cli)) instead of the minimal config below.

```yaml
# otel-collector-config.yaml
exporters:
  otlphttp/respan:
    endpoint: "https://api.respan.ai/api"
    headers:
      Authorization: "Bearer YOUR_RESPAN_API_KEY"

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlphttp/respan]
```

## Supported semantic conventions

Respan automatically maps attributes from three major ecosystems into queryable fields. You can mix and match — all are supported simultaneously.

### GenAI semantic conventions

The [OTel GenAI semantic conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/) are the emerging standard for LLM observability.

| Attribute                              | Respan field                           |
| -------------------------------------- | -------------------------------------- |
| `gen_ai.request.model`                 | Model                                  |
| `gen_ai.response.model`                | Model (response)                       |
| `gen_ai.usage.prompt_tokens`           | Prompt tokens                          |
| `gen_ai.usage.completion_tokens`       | Completion tokens                      |
| `gen_ai.request.temperature`           | Temperature                            |
| `gen_ai.request.max_tokens`            | Max tokens                             |
| `gen_ai.system`                        | Provider                               |
| `llm.request.type`                     | Log type (chat, completion, embedding) |
| `llm.is_streaming`                     | Streaming flag                         |
| `llm.usage.total_tokens`               | Total tokens                           |
| `llm.usage.reasoning_tokens`           | Reasoning tokens                       |
| `gen_ai.usage.cache_read_input_tokens` | Cached tokens                          |

### Traceloop (OpenLLMetry) conventions

Used by [Traceloop](https://github.com/traceloop/openllmetry) and the Respan tracing SDK. These provide workflow/task structure.

| Attribute                 | Respan field                            |
| ------------------------- | --------------------------------------- |
| `traceloop.span.kind`     | Span type (workflow, task, tool, agent) |
| `traceloop.entity.path`   | Hierarchical span path                  |
| `traceloop.entity.input`  | Span input                              |
| `traceloop.entity.output` | Span output                             |
| `traceloop.workflow.name` | Workflow name                           |

### OpenInference conventions

Used by [OpenInference](https://github.com/Arize-ai/openinference) instrumentors (Arize Phoenix). Respan automatically enriches these into Traceloop/GenAI equivalents.

| OpenInference attribute      | Mapped to                        |
| ---------------------------- | -------------------------------- |
| `openinference.span.kind`    | `traceloop.span.kind`            |
| `llm.model_name`             | `gen_ai.request.model`           |
| `llm.token_count.prompt`     | `gen_ai.usage.prompt_tokens`     |
| `llm.token_count.completion` | `gen_ai.usage.completion_tokens` |
| `input.value`                | `traceloop.entity.input`         |
| `output.value`               | `traceloop.entity.output`        |

This means any OpenInference instrumentor works with Respan out of the box — install the instrumentor, point OTLP at Respan, and traces appear with full model/token/input/output data.

### Respan-specific attributes

For user tracking, grouping, and metadata:

| Attribute                                    | Description                     |
| -------------------------------------------- | ------------------------------- |
| `respan.customer_params.customer_identifier` | Customer/user identifier        |
| `respan.threads.thread_identifier`           | Thread/conversation ID          |
| `respan.trace.trace_group_identifier`        | Group related traces            |
| `respan.metadata`                            | JSON merged into span metadata  |
| `respan.environment`                         | Environment tag (prod, staging) |

All other attributes are preserved in the span's metadata and are queryable in the Respan dashboard.

## Using with third-party instrumentors

Any OTel-compatible instrumentation library works with Respan. Just set the OTLP exporter environment variables and install the instrumentor.

### Traceloop (OpenLLMetry)

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

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

OpenAIInstrumentor().instrument()
# All OpenAI calls are now traced and sent to Respan
```

### OpenInference

```bash
pip install openinference-instrumentation-openai
```

```python
from openinference.instrumentation.openai import OpenAIInstrumentor

OpenAIInstrumentor().instrument()
# OpenInference spans are auto-enriched by Respan
```

### OpenInference span processors

Convert traces from other formats into OpenInference-compatible spans:

```bash
pip install openinference-instrumentation-openllmetry  # Convert Traceloop traces
pip install openinference-instrumentation-openlit       # Convert OpenLIT traces
```

## Configuration reference

| Variable                      | Value                                      |
| ----------------------------- | ------------------------------------------ |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | `https://api.respan.ai/api`                |
| `OTEL_EXPORTER_OTLP_HEADERS`  | `Authorization=Bearer YOUR_RESPAN_API_KEY` |
| `OTEL_EXPORTER_OTLP_PROTOCOL` | `http/json` or `http/protobuf`             |

Direct endpoint: `https://api.respan.ai/api/v2/traces` (for SDK configuration without the base endpoint auto-discovery).