Strawberry Python SDK

Server-side SDK for shipping analytics events, errors, logs, and LLM call telemetry to a Strawberry backend. Stdlib-only, zero external dependencies.

Install

pip install git+https://github.com/steventruong/strawberry-python.git@v1.0.0

Requires Python 3.9+.

Quick start

import strawberry

strawberry.init(
    api_key="berry_xxxxxxxx",
    host="https://straw.berryagents.com",
    release_version="v1.2.3",
    environment="production",
)

strawberry.capture("user_signed_up", {"plan": "pro"}, distinct_id="user_123")
strawberry.identify("user_123", {"email_domain": "example.com"})
strawberry.log("info", "worker started", category="ingest")
strawberry.llm_call("openai", "gpt-4o", prompt_tokens=1200, completion_tokens=210)

try:
    1 / 0
except Exception as exc:
    strawberry.capture_error(exc, context={"where": "demo"})

strawberry.flush()
strawberry.shutdown()

Public API

Function	Purpose
init(api_key, host, release_version, environment)	Configure the SDK. Idempotent. Safe to call with empty key (no-op).
is_enabled()	Returns True when the SDK is initialized with a non-empty key.
capture(event, props, distinct_id, timestamp)	Queue a custom event for batched delivery.
identify(distinct_id, props)	Emit $identify.
capture_error(err, context)	POST an error event to /api/v1/errors/ingest. Accepts Exception or string.
log(level, message, category, attrs)	POST a log entry to /api/v1/logs.
llm_call(provider, model, ...)	Emit $llm_call with token/cost/latency props.
flush()	Best-effort drain of in-memory queues.
shutdown()	Stop the worker, final drain.
middleware(app)	ASGI wrapper. Emits $http_request and $http_error.

ASGI integration (FastAPI, Starlette, etc.)

from fastapi import FastAPI
import strawberry

strawberry.init(api_key="berry_xxxxxxxx", release_version="v1.2.3")

app = FastAPI()
app.add_middleware  # your own middlewares first
app = strawberry.middleware(app)

Distinct ID is extracted automatically from the X-User-Id header or the sub claim of a Bearer JWT (no verification, observability only).

Behavior

• Events are batched and flushed every 5 seconds or when 50 events are queued.
• Errors and logs are posted individually.
• Retries on 5xx or 429 with backoff at 0.5s, 1s, 2s (max 3 retries).
• atexit hook flushes on shutdown.
• All calls are non-blocking and never raise.

Configuration via environment

If STRAWBERRY_AUTO_INIT=1 is set, the SDK auto-initializes from STRAWBERRY_API_KEY, STRAWBERRY_HOST, RELEASE_VERSION, STRAWBERRY_ENV. Opt-in only.