Metadata-Version: 2.4
Name: observe-sdk
Version: 0.1.0
Summary: Lightweight observability SDK for Python
Author-email: Kelechukwu Amadi-Keke <favourkaycee23@gmail.com>
License: MIT
Project-URL: Homepage, https://observe.dev
Project-URL: Repository, https://github.com/im-kaycee/observability-python-sdk
Keywords: analytics,observability,monitoring
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.27.0

# 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

```bash
pip install observe-sdk
```

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

## Quick start

```python
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:

```python
# 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`:

```python
# 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,
        })
```

```python
# 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

```bash
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
