> ## Documentation Index
> Fetch the complete documentation index at: https://docs.portkey.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenTelemetry Python SDK

> Direct OpenTelemetry instrumentation with full control over traces and intelligent gateway routing

The [OpenTelemetry SDK](https://opentelemetry.io/docs/languages/python/) provides direct, fine-grained control over instrumentation in your LLM applications. Unlike automatic instrumentation libraries, the SDK allows you to manually create spans and set attributes exactly where and how you need them.

> [!NOTE]
>
> Using the OpenTelemetry SDK directly with Portkey gives you complete control over what gets traced while benefiting from Portkey's intelligent gateway features like caching, fallbacks, and load balancing.

## Why OpenTelemetry SDK + Portkey?

> [card] Full Control
>
> Manually instrument exactly what you need with custom spans and attributes

> [card] Production Ready
>
> Battle-tested OpenTelemetry standard used by enterprises worldwide

> [card] Custom Attributes
>
> Add any metadata you need to traces for debugging and analysis

> [card] Gateway Intelligence
>
> Portkey adds routing optimization and resilience to your LLM calls

## Quick Start

### Prerequisites

* Python
* Portkey account with API key
* OpenAI API key (or add it to [Model Catalog](https://docs.portkey.ai/docs/product/model-catalog.md))

### Step 1: Install Dependencies

Install the required packages:

```bash theme={"system"}
pip install opentelemetry-api opentelemetry-sdk opentelemetry-exporter-otlp-proto-http openai portkey-ai
```

### Step 2: Configure OpenTelemetry

Set up the tracer provider and OTLP exporter:

```python theme={"system"}
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

# Setup tracer provider
provider = TracerProvider()
trace.set_tracer_provider(provider)

# Configure OTLP exporter to send to Portkey
otlp_exporter = OTLPSpanExporter(
    endpoint="https://api.portkey.ai/v1/otel/v1/traces",
    headers={
        "x-portkey-api-key": "YOUR_PORTKEY_API_KEY",
    }
)

# Add batch span processor (recommended for production)
span_processor = BatchSpanProcessor(otlp_exporter)
provider.add_span_processor(span_processor)

# Get tracer
tracer = trace.get_tracer(__name__)
```

### Step 3: Configure Portkey Gateway

Set up the OpenAI client with Portkey's gateway:

```python theme={"system"}
from openai import OpenAI
from portkey_ai import createHeaders

# Use Portkey's gateway for intelligent routing
client = OpenAI(
    api_key="PORTKEY_API_KEY",
    base_url="https://api.portkey.ai/v1",
    default_headers=createHeaders(
        api_key="PORTKEY_API_KEY",
        provider="@openai-prod"  # Your AI Provider slug from Model Catalog
    )
)
```

### Step 4: Create Instrumented Functions

Manually instrument your LLM calls with custom spans:

```python theme={"system"}
def generate_ai_response(input_text):
    with tracer.start_as_current_span("OpenAI-Chat-Completion") as span:
        # Add input attributes
        span.set_attribute("input.value", input_text)
        span.set_attribute("model.name", "gpt-4o")
        span.set_attribute("temperature", 0.7)
        span.set_attribute("gen_ai.prompt.0.role", "user")
        span.set_attribute("gen_ai.prompt.0.content", input_text)

        # Make the API call
        response = client.chat.completions.create(
            messages=[{"role": "user", "content": input_text}],
            model="gpt-4o",
            temperature=0.7,
        )

        # Add response attributes
        output_content = response.choices[0].message.content
        span.set_attribute("output.value", output_content)
        span.set_attribute("gen_ai.completion.0.role", "assistant")
        span.set_attribute("gen_ai.completion.0.content", output_content)

        return output_content
```

## Complete Example

Here's a full working example:

```python theme={"system"}
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
from openai import OpenAI
from portkey_ai import createHeaders

# Step 1: Setup OpenTelemetry
provider = TracerProvider()
trace.set_tracer_provider(provider)

otlp_exporter = OTLPSpanExporter(
    endpoint="https://api.portkey.ai/v1/otel/v1/traces",
    headers={"x-portkey-api-key": "YOUR_PORTKEY_API_KEY"}
)

span_processor = BatchSpanProcessor(otlp_exporter)
provider.add_span_processor(span_processor)

tracer = trace.get_tracer(__name__)

# Step 2: Configure Portkey Gateway
client = OpenAI(
    api_key="PORTKEY_API_KEY",
    base_url="https://api.portkey.ai/v1",
    default_headers=createHeaders(
        api_key="PORTKEY_API_KEY",
        provider="@openai-prod"
    )
)

# Step 3: Create instrumented function
def generate_ai_response(input_text):
    with tracer.start_as_current_span("OpenAI-Chat-Completion") as span:
        # Set input attributes
        span.set_attribute("input.value", input_text)
        span.set_attribute("model.name", "gpt-4o")
        span.set_attribute("temperature", 0.7)

        # Make API call
        response = client.chat.completions.create(
            messages=[{"role": "user", "content": input_text}],
            model="gpt-4o",
            temperature=0.7,
        )

        # Set output attributes
        output_content = response.choices[0].message.content
        span.set_attribute("output.value", output_content)

        return output_content

# Step 4: Use the instrumented function
if __name__ == "__main__":
    input_text = "Explain the concept of AI in 50 words"
    response = generate_ai_response(input_text)
    print(response)
```

## Next Steps

> [card] [Configure Gateway](https://docs.portkey.ai/docs/product/ai-gateway/configs.md)
>
> Set up intelligent routing, fallbacks, and caching

> [card] [Model Catalog](https://docs.portkey.ai/docs/product/model-catalog.md)
>
> Manage AI providers, credentials, and model access centrally

> [card] [View Analytics](https://docs.portkey.ai/docs/product/observability/analytics.md)
>
> Analyze costs, performance, and usage patterns

> [card] [Set Up Alerts](https://docs.portkey.ai/docs/product/observability/analytics.md)
>
> Configure alerts for anomalies and performance issues

***

## See Your Traces in Action

Once configured, navigate to the [Portkey dashboard](https://app.portkey.ai/logs) to see your custom OpenTelemetry traces enhanced with gateway intelligence:

![OpenTelemetry traces in Portkey](https://mintcdn.com/portkey-docs/Buc1Vm2P31GSPm3S/images/product/opentelemetry.png?fit=max\&auto=format\&n=Buc1Vm2P31GSPm3S\&q=85\&s=bc982b581d5ce60764d207b004b4677f)

***

> [card] [Portkey is now PRISMA AIRS AI Gateway. See it in action.](https://www.paloaltonetworks.in/ai-security/ai-gateway?utm_source=portkey\&utm_medium=referral\&utm_campaign=prisma_airs\&utm_content=docs_nav#contact)
>
> Contact Us


## Related topics

- [OpenAI Agents SDK (Python)](https://docs.portkey.ai/docs/integrations/agents/openai-agents.md)
- [OpenTelemetry for LLM Observability](https://docs.portkey.ai/docs/product/observability/opentelemetry.md)
- [Observability (OpenTelemetry)](https://docs.portkey.ai/docs/product/observability.md)
- [OpenTelemetry(OTel) Export](https://docs.portkey.ai/docs/product/enterprise-offering/otel/otel.md)
- [OpenLIT](https://docs.portkey.ai/docs/integrations/tracing-providers/openlit.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.