> 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/_mcp/server.

# LiteLLM (tracing)

> Trace LiteLLM calls with Respan - native callback instrumentation, gateway routing, and full observability.

[LiteLLM](https://www.litellm.ai/) provides a unified Python interface for calling 100+ LLM providers using the OpenAI format. Respan's LiteLLM instrumentation registers a native LiteLLM callback and sends completion spans through `respan-tracing`, with optional gateway routing through the OpenAI-compatible Respan endpoint.

#### Set up Respan

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

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

#### Use Respan Gateway

See [LiteLLM gateway setup](/docs/gateway/litellm) to route this integration through the Respan gateway.

#### Example projects

* [Example projects root](https://github.com/respanai/respan-example-projects)

## Setup

#### Install packages

```bash
pip install respan-ai respan-instrumentation-litellm litellm
```

#### Set environment variables

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

`OPENAI_API_KEY` (or any provider key) is used for LLM requests. `RESPAN_API_KEY` is used to export traces to Respan.

#### Initialize and run

Initialize Respan with the LiteLLM instrumentor. Requests go directly to providers; the callback emits canonical chat spans to Respan.

```python
import os

import litellm
from respan import Respan
from respan_instrumentation_litellm import LiteLLMInstrumentor

respan = Respan(
    api_key=os.environ["RESPAN_API_KEY"],
    app_name="litellm-service",
    instrumentations=[LiteLLMInstrumentor()],
)

response = litellm.completion(
    model="gpt-4.1-nano",
    messages=[{"role": "user", "content": "Say hello in three languages."}],
)
print(response.choices[0].message.content)
```

#### View your trace

Open the [Traces page](https://platform.respan.ai/platform/traces) to see your LiteLLM completions across providers as auto-traced spans.

## Configuration

### Respan

| Parameter          | Type          | Default                   | Description                                                  |
| ------------------ | ------------- | ------------------------- | ------------------------------------------------------------ |
| `api_key`          | `str \| None` | `RESPAN_API_KEY` env var  | Respan API key used for trace export.                        |
| `base_url`         | `str \| None` | `RESPAN_BASE_URL` env var | Respan API base URL.                                         |
| `app_name`         | `str`         | `"respan"`                | Service name shown on exported spans.                        |
| `instrumentations` | `list`        | `[]`                      | Include `LiteLLMInstrumentor()` to activate LiteLLM tracing. |

### LiteLLMInstrumentor

| Parameter         | Type   | Default | Description                                                            |
| ----------------- | ------ | ------- | ---------------------------------------------------------------------- |
| `include_content` | `bool` | `True`  | Capture request messages and assistant response content on chat spans. |

See the [LiteLLM SDK reference](/docs/sdks/python/exporters/litellm) for the full API.

## Attributes

Set defaults on `Respan(...)`, or override attributes per request with `propagate_attributes`.

```python
with respan.propagate_attributes(
    customer_identifier="user-123",
    thread_identifier="conv_abc_123",
    trace_group_identifier="litellm-support-flow",
    metadata={"plan": "pro"},
):
    response = litellm.completion(
        model="gpt-4.1-nano",
        messages=[{"role": "user", "content": "Hello!"}],
    )
```

| Attribute                | Description                                     |
| ------------------------ | ----------------------------------------------- |
| `customer_identifier`    | Identifies the end user in Respan analytics.    |
| `thread_identifier`      | Groups related messages into a conversation.    |
| `trace_group_identifier` | Groups related traces for search and filtering. |
| `metadata`               | Custom key-value pairs attached to the span.    |

## Async usage

The callback supports async completions automatically.

```python
import litellm
from respan import Respan
from respan_instrumentation_litellm import LiteLLMInstrumentor

respan = Respan(instrumentations=[LiteLLMInstrumentor()])

response = await litellm.acompletion(
    model="gpt-4.1-nano",
    messages=[{"role": "user", "content": "Tell me a joke"}],
)
```

## Multiple providers

LiteLLM's unified interface means all providers are logged with the same callback.

```python
import litellm
from respan import Respan
from respan_instrumentation_litellm import LiteLLMInstrumentor

respan = Respan(instrumentations=[LiteLLMInstrumentor()])

litellm.completion(model="gpt-4.1-nano", messages=[...])
litellm.completion(model="claude-sonnet-4-5-20250929", messages=[...])
litellm.completion(model="together_ai/meta-llama/Llama-3-70b", messages=[...])
```