observe-sdk 0.1.0__tar.gz

observe_sdk-0.1.0/MANIFEST.in

@@ -0,0 +1,2 @@
+include src/tracker.py
+include README.md

observe_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,194 @@
+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

observe_sdk-0.1.0/README.md

@@ -0,0 +1,181 @@
+# 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

observe_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,17 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+[project]
+name = "observe-sdk"
+version = "0.1.0"
+description = "Lightweight observability SDK for Python"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "Kelechukwu Amadi-Keke", email = "favourkaycee23@gmail.com" }]
+keywords = ["analytics", "observability", "monitoring"]
+requires-python = ">=3.9"
+dependencies = ["httpx>=0.27.0"]
+
+[project.urls]
+Homepage = "https://observe.dev"
+Repository = "https://github.com/im-kaycee/observability-python-sdk"

observe_sdk-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

observe_sdk-0.1.0/src/observe_sdk.egg-info/PKG-INFO

@@ -0,0 +1,194 @@
+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

observe_sdk-0.1.0/src/observe_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,9 @@
+MANIFEST.in
+README.md
+pyproject.toml
+src/tracker.py
+src/observe_sdk.egg-info/PKG-INFO
+src/observe_sdk.egg-info/SOURCES.txt
+src/observe_sdk.egg-info/dependency_links.txt
+src/observe_sdk.egg-info/requires.txt
+src/observe_sdk.egg-info/top_level.txt

observe_sdk-0.1.0/src/observe_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

observe_sdk-0.1.0/src/observe_sdk.egg-info/requires.txt

@@ -0,0 +1 @@
+httpx>=0.27.0

observe_sdk-0.1.0/src/observe_sdk.egg-info/top_level.txt

@@ -0,0 +1 @@
+tracker

observe_sdk-0.1.0/src/tracker.py

@@ -0,0 +1,75 @@
+import traceback
+import threading
+import httpx
+from typing import Any
+
+
+class Tracker:
+    def __init__(self, api_key: str, server_url: str):
+        if not api_key:
+            raise ValueError("Tracker: api_key is required")
+        if not server_url:
+            raise ValueError("Tracker: server_url is required")
+
+        self._api_key = api_key
+        self._server_url = server_url.rstrip("/")
+        self._headers = {
+            "Authorization": f"Bearer {self._api_key}",
+            "Content-Type": "application/json",
+        }
+
+    # ---- Tracking ----
+
+    def track(self, event_name: str, anonymous_id: str, properties: dict[str, Any] = {}):
+        """Track a custom server-side event."""
+        if not event_name:
+            return
+        self._send("/ingest/events", {
+            "name": event_name,
+            "anonymous_id": anonymous_id,
+            "properties": properties,
+        })
+
+    def identify(self, anonymous_id: str, user_id: str):
+        """Link an anonymous_id to a known user_id."""
+        self._send("/ingest/identify", {
+            "anonymous_id": anonymous_id,
+            "user_id": str(user_id),
+        })
+
+    def capture_exception(self, e: Exception, anonymous_id: str = "server", extra: dict = {}):
+        """Capture an exception and send it as an event with the stack trace."""
+        self.track(
+            event_name="exception",
+            anonymous_id=anonymous_id,
+            properties={
+                "exception_type": type(e).__name__,
+                "message": str(e),
+                "stack_trace": traceback.format_exc(),
+                **extra,
+            },
+        )
+
+    # ---- Transport ----
+
+    def _send(self, endpoint: str, payload: dict):
+        """Fire and forget — runs in a background thread so it never blocks."""
+        thread = threading.Thread(
+            target=self._post,
+            args=(endpoint, payload),
+            daemon=True,
+        )
+        thread.start()
+
+    def _post(self, endpoint: str, payload: dict):
+        try:
+            with httpx.Client() as client:
+                client.post(
+                    f"{self._server_url}{endpoint}",
+                    json=payload,
+                    headers=self._headers,
+                    timeout=5.0,
+                )
+        except Exception as e:
+            # fail silently — tracking should never crash the host app
+            print(f"Tracker: failed to send event — {e}")