raindrop-azure-openai 0.0.7

Raindrop observability integration for Azure OpenAI

raindrop-azure-openai

Raindrop observability integration for Azure OpenAI (Python). Automatically captures chat.completions.create() calls by wrapping AzureOpenAI and AsyncAzureOpenAI clients.

Installation

pip install raindrop-azure-openai openai

Quick Start

from raindrop_azure_openai import RaindropAzureOpenAI
from openai import AzureOpenAI

raindrop = RaindropAzureOpenAI(
    api_key="rk_...",
    user_id="user-123",
    debug=False,  # set True for verbose logging
)

client = AzureOpenAI(
    azure_endpoint="https://your-resource.openai.azure.com",
    api_key="...",
    api_version="2024-10-21",
)
wrapped = raindrop.wrap(client)

response = wrapped.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Hello!"}],
)

raindrop.shutdown()

Projects

Route events to a specific project by passing its slug as project_id:

raindrop = RaindropAzureOpenAI(
    api_key="rk_...",
    project_id="support-prod",
)

project_id sets the X-Raindrop-Project-Id header on every event. Omit it (or pass "default") to use your org's default Production project, which is the existing behavior. The same option is accepted by the create_raindrop_azure_openai(...) factory. Invalid slugs are ignored with a warning and no header is sent.

Debug Mode

raindrop = RaindropAzureOpenAI(api_key="rk_...", debug=True)

When debug=True, verbose logs are emitted to the raindrop_azure_openai logger at DEBUG level.

Async Support

from raindrop_azure_openai import RaindropAzureOpenAI
from openai import AsyncAzureOpenAI

raindrop = RaindropAzureOpenAI(api_key="rk_...", user_id="user-123")

client = AsyncAzureOpenAI(
    azure_endpoint="https://your-resource.openai.azure.com",
    api_key="...",
    api_version="2024-10-21",
)
wrapped = raindrop.wrap(client)

response = await wrapped.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Hello!"}],
)

raindrop.shutdown()

User Identification

raindrop.identify("user-123", traits={"plan": "pro", "name": "Alice"})

Tracking Signals

raindrop.track_signal(
    event_id="evt-abc",
    name="thumbs_up",
    signal_type="feedback",
    sentiment="POSITIVE",
    comment="Great response!",
)

Flushing and Shutdown

raindrop.flush()     # flush pending data
raindrop.shutdown()  # flush + release resources

Factory Function (Backwards-Compatible)

from raindrop_azure_openai import create_raindrop_azure_openai

raindrop = create_raindrop_azure_openai(api_key="rk_...", user_id="user-123")
# raindrop is now a RaindropAzureOpenAI instance with .wrap(), .flush(), .shutdown()

What Gets Captured

• Chat completions — input messages, output text, model, token usage
• Finish reason — azure_openai.finish_reason (stop, length, content_filter, tool_calls)
• Extended tokens — ai.usage.cached_tokens (prompt cache hits) and ai.usage.thoughts_tokens (reasoning tokens for o1/o3 models)
• Errors — error type and message captured as properties, then re-raised to the caller
• Async support — both sync (AzureOpenAI) and async (AsyncAzureOpenAI) clients are instrumented

Configuration

Option	Type	Default	Description
api_key	str | None	None	Raindrop API key. None disables telemetry shipping
user_id	str | None	None	Associate all events with a user (falls back to "unknown")
convo_id	str | None	None	Group events into a conversation
project_id	str | None	None	Route events to a specific project (slug); omit for the default Production project
tracing_enabled	bool	True	Enable OTEL-based tracing
bypass_otel_for_tools	bool	True	Bypass OTEL for tool calls
disable_auto_instrument	bool	True	Library auto-instrumentation is opt-in (see below)
debug	bool	False	Enable verbose debug logging

Library auto-instrumentation is opt-in

As of 0.0.4, disable_auto_instrument defaults to True: the integration no longer lets Traceloop monkey-patch every LLM client library it recognizes in your process (the OpenAI client itself, Anthropic, botocore, etc.). The wrapper captures input/output, token usage, model name, and finish_reason directly from the wrapped client's responses, so no library patching is needed for full dashboards.

If you specifically want LLM-call-level spans from library instrumentation and have verified compatibility in your environment, opt back in with disable_auto_instrument=False.

Double-Wrap Protection

Calling wrap() on an already-instrumented client is a safe no-op — the client is returned unchanged.

Full Documentation

See the Raindrop docs for the complete reference.

Testing

cd packages/azure-openai-python
pip install -e ".[dev]"
python -m pytest tests/ -v

License

MIT