Observra Python SDK

observra routes your application's LLM calls through the Observra Gateway and traces them, so every request appears in your dashboard with its model, tokens, latency, and errors — without changing how you call the model.

The whole integration

Two lines added to an application that already calls an LLM:

import os

import observra
from openai import OpenAI

observra.configure()
observra.instrument()

# Unchanged. Stock OpenAI SDK, straight from its own documentation.
client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])
response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Hello"}],
)

configure() reads your gateway key from OBSERVRA_GATEWAY_KEY, points at Observra's hosted gateway, and patches supported httpx provider transports. A request that would have gone to api.openai.com goes to your gateway instead, with credentials remapped correctly. instrument() adds lifecycle spans for supported agent frameworks.

That works for 13 provider integrations and for agent frameworks built on them.

What you get

A gateway observation per call — provider, model, input/output tokens, latency, status
A trace id shared by every call in one logical operation, so a multi-step agent run reads as a single flow instead of unrelated rows
A span describing the call, correlated to that observation
Guardrail annotations that scan prompts and responses for PII and secrets

None of it can break your application. Telemetry failures are swallowed by design: if tracing fails, your LLM call still runs.

The other integration path

Patching provider transports is not acceptable everywhere. For explicit, hand-built HTTP requests, use the SDK's gateway helpers instead:

import os

import httpx
import observra

observra.configure()

response = httpx.post(
    observra.gateway_url("groq", "/openai/v1/chat/completions"),
    headers={
        **observra.gateway_headers(
            "groq",
            provider_key=os.environ["GROQ_API_KEY"],
        ),
        "content-type": "application/json",
    },
    json={
        "model": "llama-3.3-70b-versatile",
        "messages": [{"role": "user", "content": "Hello"}],
    },
)
response.raise_for_status()

This bypasses provider-SDK interception. You build the request and parse the response, while Observra provides the gateway URL and correctly named authentication headers.

Which to choose

	Keep your provider SDK	Use gateway helpers
Code changes	Two lines, once	Build each HTTP request
Provider API coverage	Everything your SDK does	Endpoints you implement
Patches HTTP transports	Yes	No provider transport patch required
Agent frameworks	Works	Not applicable
Response types	Your SDK's own	Raw `httpx.Response`

Keep your provider SDK is the better default. Use gateway helpers when provider transport patching is unacceptable, or when you need direct gateway HTTP access.

Requirements

Python 3.9 or later
observra
A provider SDK or framework package for your application

pip install observra openai

What you need before starting

One credential: a gateway key from the Observra Dashboard under Gateway Keys. It starts with obs_ and identifies which Application and Environment your calls belong to.

It is not a provider API key. You keep sending your provider key yourself; Observra forwards it to the provider and does not store it in span attributes.

Set it as OBSERVRA_GATEWAY_KEY and configure() picks it up with no arguments.

Quickstart — exactly which lines to add, and where
Configuration — every option
Providers — the full provider list
Frameworks — tracing multi-step agent runs

The whole integration​

What you get​

The other integration path​

Which to choose​

Requirements​

What you need before starting​

Next​