Skip to main content

Quickstart

Add Observra before constructing provider clients.

1. Install​

pip install observra openai

2. Set gateway key​

Create an Observra gateway key, then set it outside source control:

export OBSERVRA_GATEWAY_KEY="obs_live_xxx"

3. Configure once​

app.py
import os

import observra
from openai import OpenAI

observra.configure(
    gateway_key=os.environ["OBSERVRA_GATEWAY_KEY"],
)

client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])
response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Explain observability in one sentence."}],
)
print(response.choices[0].message.content)

configure() must run before a client creates its HTTP transport. Calls to supported provider hosts then route through the gateway automatically.

4. Add framework instrumentation when needed​

Direct provider SDK and raw httpx calls need configure() only. Call instrument() for installed agent frameworks:

observra.configure(gateway_key=os.environ["OBSERVRA_GATEWAY_KEY"])
observra.instrument()

instrument() is synchronous and idempotent. Call it once at process startup, before framework clients and agents run.

Verify routing​

A provider error returned through the gateway, such as an unavailable model, insufficient credits, or invalid provider key, proves routing reached the provider. A successful response also creates a trace span.

If no traces appear:

  1. Confirm OBSERVRA_GATEWAY_KEY or gateway_key is present.
  2. Ensure configure() ran before the provider client was constructed.
  3. Check provider host appears in Providers.

Next​