observe-sdk 0.1.0

Lightweight observability SDK for Python

observe. — Python SDK

The Python SDK for observe. Track server-side events, capture exceptions, and monitor API performance from any Python application.

Features

• Custom event tracking
• Exception capture with full stack traces
• User identification
• Fire and forget — sends in background threads, never blocks your app
• Works with FastAPI, Django, Flask, or plain Python

Installation

pip install observe-sdk

Until published to PyPI, copy src/tracker.py into your project directly.

Quick start

from tracker import Tracker

tracker = Tracker(
    api_key="obs_your_secret_key",
    server_url="https://api.observe.dev",
)

# track an event
tracker.track(
    event_name="order_placed",
    anonymous_id="anon_abc123",
    properties={"plan": "pro"},
)

# capture an exception
try:
    process_payment()
except Exception as e:
    tracker.capture_exception(e, extra={"user_id": "user_123"})

Framework guides

FastAPI

Add the middleware to automatically track all requests:

# main.py
from fastapi import FastAPI, Request
from tracker import Tracker
import time

app = FastAPI()

tracker = Tracker(
    api_key="obs_your_secret_key",
    server_url="https://api.observe.dev",
)

@app.middleware("http")
async def track_requests(request: Request, call_next):
    start = time.time()
    try:
        response = await call_next(request)
        duration_ms = round((time.time() - start) * 1000)
        tracker.track(
            event_name="api_request",
            anonymous_id="server",
            properties={
                "method": request.method,
                "path": request.url.path,
                "status_code": response.status_code,
                "duration_ms": duration_ms,
            },
        )
        return response
    except Exception as e:
        tracker.capture_exception(e, extra={"path": request.url.path})
        raise

Django

Create a middleware file and add it to settings.py:

# observe_middleware.py
import time
from tracker import Tracker

tracker = Tracker(
    api_key="obs_your_secret_key",
    server_url="https://api.observe.dev",
)

class ObserveMiddleware:
    def __init__(self, get_response):
        self.get_response = get_response

    def __call__(self, request):
        start = time.time()
        response = self.get_response(request)
        duration_ms = round((time.time() - start) * 1000)

        tracker.track(
            event_name="api_request",
            anonymous_id=str(request.user.id) if request.user.is_authenticated else "anon",
            properties={
                "method": request.method,
                "path": request.path,
                "status_code": response.status_code,
                "duration_ms": duration_ms,
            },
        )
        return response

    def process_exception(self, request, exception):
        tracker.capture_exception(exception, extra={
            "path": request.path,
            "method": request.method,
        })

# settings.py
MIDDLEWARE = [
    # ... existing middleware
    "yourapp.observe_middleware.ObserveMiddleware",
]

API reference

Tracker(api_key, server_url)

Parameter	Type	Required	Description
api_key	str	Yes	Your project secret key
server_url	str	Yes	Your observe. server URL

tracker.track(event_name, anonymous_id, properties?)

Parameter	Type	Required	Description
event_name	str	Yes	Name of the event
anonymous_id	str	Yes	Session or visitor ID
properties	dict	No	Any additional data

tracker.identify(anonymous_id, user_id)

Parameter	Type	Required	Description
anonymous_id	str	Yes	Current session ID
user_id	str	Yes	Your user's ID

tracker.capture_exception(exception, anonymous_id?, extra?)

Parameter	Type	Required	Description
exception	Exception	Yes	The caught exception
anonymous_id	str	No	Defaults to "server"
extra	dict	No	Any additional context

Development

git clone https://github.com/yourname/observability-python-sdk.git
cd observability-python-sdk
pip install httpx

# run the example
python examples/basic.py

License

MIT