Installation
pip install fallom openai
Quick Start
Import order matters! Initialize Fallom before importing OpenAI.
import os
# Import and initialize Fallom FIRST
import fallom
fallom.init(api_key=os.environ["FALLOM_API_KEY"])
# NOW import OpenAI
from openai import OpenAI
client = OpenAI()
# Set session context (config_key, session_id, customer_id)
fallom.trace.set_session("my-app", "session-123", customer_id="user-456")
# Use as normal - automatically traced!
response = client.chat.completions.create(
model="gpt-4o",
messages=[{"role": "user", "content": "Hello!"}]
)
print(response.choices[0].message.content)
Why Import Order Matters
Fallom uses OpenTelemetry auto-instrumentation which patches the OpenAI library when initialized. If you import OpenAI first, the instrumentation can’t patch it properly.
# ❌ WRONG - OpenAI imported before Fallom init
from openai import OpenAI
import fallom
fallom.init() # Too late - OpenAI already loaded
# ✅ CORRECT - Fallom init before OpenAI import
import fallom
fallom.init()
from openai import OpenAI # Now it gets patched
Streaming
import fallom
fallom.init(api_key="your-fallom-api-key")
from openai import OpenAI
client = OpenAI()
fallom.trace.set_session("my-agent", "session-123")
stream = client.chat.completions.create(
model="gpt-4o",
messages=[{"role": "user", "content": "Write a poem."}],
stream=True
)
for chunk in stream:
if chunk.choices[0].delta.content:
print(chunk.choices[0].delta.content, end="")
With Azure OpenAI
import fallom
fallom.init(api_key="your-fallom-api-key")
from openai import AzureOpenAI
client = AzureOpenAI(
api_key=os.environ["AZURE_OPENAI_API_KEY"],
api_version="2024-02-01",
azure_endpoint=os.environ["AZURE_OPENAI_ENDPOINT"]
)
fallom.trace.set_session("my-agent", "session-123")
response = client.chat.completions.create(
model="gpt-4o", # Your deployment name
messages=[{"role": "user", "content": "Hello!"}]
)
Model A/B Testing
import fallom
from fallom import models
fallom.init(api_key="your-fallom-api-key")
from openai import OpenAI
client = OpenAI()
# Get assigned model for this session
model_id = models.get("my-experiment", "session-123", fallback="gpt-4o-mini")
fallom.trace.set_session("my-experiment", "session-123")
response = client.chat.completions.create(
model=model_id, # Uses A/B test assigned model
messages=[{"role": "user", "content": "Hello!"}]
)
What Gets Traced
| Field | Description |
|---|
| Model | gpt-4o, gpt-4o-mini, etc. |
| Duration | Total request time (ms) |
| Tokens | Prompt, completion, cached tokens |
| Cost | Calculated from token usage |
| Prompts | All input messages |
| Completions | Model response |
| Session | Your config key + session ID |
Next Steps