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

# OpenLIT (tracing)

> Send OpenLIT's native OpenTelemetry spans to Respan with canonical chat, embedding, tool, agent, and workflow fields.

[OpenLIT](https://openlit.io/) is an open-source observability SDK for LLM applications. `respan-instrumentation-openlit` activates OpenLIT's provider and framework instrumentation, normalizes its native OpenTelemetry spans to the Respan span contract, and exports them through the active Respan tracer provider.

The adapter does not wrap provider calls with a second Respan span. OpenLIT owns the library patches, while Respan owns normalization and export.

#### Set up Respan

Create an account at [platform.respan.ai](https://platform.respan.ai) and grab an [API key](https://platform.respan.ai/platform/gateway/api-keys).

Run `npx @respan/cli setup` to set up with your coding agent.

#### Example projects

* [Python package README](https://github.com/RespanAI/respan/tree/main/python-sdks/instrumentations/respan-instrumentation-openlit)
* [Runnable OpenLIT examples](https://github.com/respanai/respan-example-projects/tree/main/python/tracing/openlit)

## Setup

#### Install packages

```bash
pip install respan-ai respan-instrumentation-openlit openai
```

#### Set environment variables

```bash
export RESPAN_API_KEY="YOUR_RESPAN_API_KEY"
export OPENAI_API_KEY="YOUR_OPENAI_API_KEY"
```

Set `RESPAN_BASE_URL` as well when exporting to a self-hosted or non-default Respan endpoint.

#### Initialize and call an instrumented library

```python
from openai import OpenAI
from respan import Respan
from respan_instrumentation_openlit import OpenLITInstrumentor

respan = Respan(
    app_name="openlit-support-agent",
    instrumentations=[OpenLITInstrumentor()],
)
client = OpenAI()

try:
    response = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[
            {"role": "user", "content": "Why is tracing useful?"},
        ],
    )
    print(response.choices[0].message.content)
finally:
    respan.shutdown()
```

Creating `Respan` activates OpenLIT automatically. Do not call `openlit.init()` separately for the same process.

#### View your trace

Open the [Traces page](https://platform.respan.ai/platform/traces) to inspect the normalized OpenLIT span, messages, model, usage, status, and nested application context.

## What is traced

The adapter normalizes OpenLIT operation types into Respan's canonical span types.

| OpenLIT operation             | Respan log type |
| ----------------------------- | --------------- |
| Chat model call               | `chat`          |
| Text generation or completion | `text`          |
| Embedding request             | `embedding`     |
| Tool or function execution    | `tool`          |
| Agent                         | `agent`         |
| Workflow                      | `workflow`      |
| Task or evaluation step       | `task`          |
| Guardrail                     | `guardrail`     |

Model, provider, messages, tool definitions and calls, real provider token usage, standard HTTP and OpenAI attributes, and response status are retained when OpenLIT supplies them. OpenLIT-only cost, metric, framework, and legacy aliases are removed after canonical mapping. Provider failures keep their OpenTelemetry error status and include backend-visible `status_code` and `error.message` fields.

For OpenAI sync and async embedding calls, every returned vector element is stored in `traceloop.entity.output`; vectors are never dimension-truncated by the adapter. Setting `capture_content=False` omits both embedding inputs and vectors.

## Configuration

| Parameter                | Type                | Default | Description                                                                                   |
| ------------------------ | ------------------- | ------- | --------------------------------------------------------------------------------------------- |
| `capture_content`        | `bool`              | `True`  | Capture prompts, completions, embedding inputs and vectors, tool definitions, and tool calls. |
| `disabled_instrumentors` | `list[str] \| None` | `None`  | OpenLIT instrumentor names to leave disabled.                                                 |
| `pricing_json`           | `str \| None`       | `None`  | Custom OpenLIT pricing data. The default packaged file is offline and contains no prices.     |
| `instrumentations`       | `list`              | `[]`    | Pass `[OpenLITInstrumentor()]` to `Respan` to activate the adapter.                           |
| `api_key`                | `str \| None`       | `None`  | Falls back to `RESPAN_API_KEY`.                                                               |
| `base_url`               | `str \| None`       | `None`  | Falls back to `RESPAN_BASE_URL`.                                                              |

### Disable content capture

Disable content capture when prompts, responses, or tool arguments may contain sensitive data:

```python
from respan import Respan
from respan_instrumentation_openlit import OpenLITInstrumentor

respan = Respan(
    instrumentations=[OpenLITInstrumentor(capture_content=False)],
)
```

The adapter configures OpenLIT not to collect message content and also removes prompts, responses, embedding vectors, and other content fields from OpenLIT spans before export. Model, provider, usage, timing, and error fields remain available.

### Limit OpenLIT instrumentation

Use OpenLIT's `disabled_instrumentors` option when the process loads libraries that should not be patched:

```python
from respan import Respan
from respan_instrumentation_openlit import OpenLITInstrumentor

respan = Respan(
    instrumentations=[
        OpenLITInstrumentor(
            disabled_instrumentors=["anthropic", "langchain"],
        )
    ],
)
```

## Add trace context

Use propagated attributes to group OpenLIT spans with the rest of an application workflow:

```python
from respan import Respan

with Respan.propagate_attributes(
    customer_identifier="user_123",
    thread_identifier="conversation_abc",
    trace_group_identifier="support_answer_workflow",
    metadata={"plan": "pro"},
):
    response = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": "Summarize my ticket."}],
    )
```

## Avoid duplicate provider spans

Do not enable a provider-specific Respan instrumentor for the same client in the same process unless nested provider spans are intentional. For example, combining `OpenLITInstrumentor()` and a separate OpenAI instrumentor can produce two spans for one OpenAI request.

Activation is reference-counted. Shutdown removes only the OpenLIT hooks activated by this adapter and preserves instrumentation that was already active.