Skip to main content

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

FieldDescription
Modelgpt-4o, gpt-4o-mini, etc.
DurationTotal request time (ms)
TokensPrompt, completion, cached tokens
CostCalculated from token usage
PromptsAll input messages
CompletionsModel response
SessionYour config key + session ID

Next Steps