watchdock-errors 0.1.0__py3-none-any.whl

watchdock_errors/__init__.py

@@ -0,0 +1,117 @@
+"""
+watchdock-errors — Application error tracking SDK for the Watchdock platform.
+
+Quickstart:
+    import watchdock_errors
+
+    watchdock_errors.init(api_key="wdk_xxx", environment="production")
+
+    # Automatic capture via middleware (Django / FastAPI integrations).
+    # Manual capture:
+    try:
+        risky_operation()
+    except Exception as exc:
+        watchdock_errors.capture_exception(exc)
+"""
+
+from __future__ import annotations
+
+import sys
+import logging
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .config import SDKConfig
+    from .client import WatchdockClient
+
+__all__ = ["init", "capture_exception", "capture_message", "flush", "close"]
+
+_client: "WatchdockClient | None" = None
+_config: "SDKConfig | None" = None
+
+logger = logging.getLogger("watchdock_errors")
+
+
+def init(
+    api_key: str,
+    endpoint: str = "https://api.watchdock.cc",
+    environment: str = "production",
+    release: str | None = None,
+    server_name: str | None = None,
+    send_pii: bool = False,
+    before_send=None,
+    timeout: float = 1.0,
+) -> None:
+    """
+    Initialise the Watchdock Errors SDK.
+
+    Must be called once at application startup before any errors are captured.
+    """
+    global _client, _config
+
+    from .config import SDKConfig
+    from .client import WatchdockClient
+
+    _config = SDKConfig(
+        api_key=api_key,
+        endpoint=endpoint,
+        environment=environment,
+        release=release,
+        server_name=server_name,
+        send_pii=send_pii,
+        before_send=before_send,
+        timeout=timeout,
+    )
+    _client = WatchdockClient(_config)
+
+
+def capture_exception(exc: BaseException | None = None, request_context: dict | None = None) -> None:
+    """
+    Capture an exception and send it to Watchdock.
+
+    If ``exc`` is None the current exception from ``sys.exc_info()`` is used.
+    Safe to call outside of an except block — does nothing if there is no
+    active exception and ``exc`` is not provided.
+    """
+    if _client is None or _config is None:
+        return
+
+    if exc is None:
+        exc_info = sys.exc_info()
+        exc = exc_info[1]
+
+    if exc is None:
+        return
+
+    from .event import build_event
+
+    event = build_event(exc, _config, request_context=request_context)
+    if event is not None:
+        _client.capture(event)
+
+
+def capture_message(message: str, request_context: dict | None = None) -> None:
+    """Capture an arbitrary message string and send it to Watchdock."""
+    if _client is None or _config is None:
+        return
+
+    from .event import build_event
+
+    event = build_event(None, _config, message=message, request_context=request_context)
+    if event is not None:
+        _client.capture(event)
+
+
+def flush(timeout: float = 2.0) -> None:
+    """Block until all queued events have been sent or timeout expires."""
+    if _client is not None:
+        _client.flush(timeout=timeout)
+
+
+def close() -> None:
+    """Gracefully shut down the SDK and drain the event queue."""
+    global _client, _config
+    if _client is not None:
+        _client.close()
+    _client = None
+    _config = None

watchdock_errors/client.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+import logging
+import queue
+import threading
+from typing import TYPE_CHECKING
+
+import requests
+
+if TYPE_CHECKING:
+    from .config import SDKConfig
+
+logger = logging.getLogger("watchdock_errors")
+
+
+class WatchdockClient:
+    """
+    Non-blocking HTTP transport for error events.
+
+    Events are enqueued and sent by a daemon background thread so the
+    calling thread is never delayed by network I/O.
+    """
+
+    def __init__(self, config: SDKConfig) -> None:
+        self._config = config
+        self._queue: queue.Queue[dict | None] = queue.Queue(maxsize=100)
+        self._thread = threading.Thread(target=self._worker, daemon=True, name="watchdock-errors")
+        self._thread.start()
+
+    def capture(self, event: dict) -> None:
+        """Enqueue an event for asynchronous delivery. Never blocks or raises."""
+        try:
+            self._queue.put_nowait(event)
+        except queue.Full:
+            logger.debug("watchdock_errors: event queue full, dropping event")
+
+    def flush(self, timeout: float = 2.0) -> None:
+        """Block until the queue is drained or timeout expires."""
+        self._queue.join()
+
+    def close(self) -> None:
+        """Signal the worker thread to stop after draining the queue."""
+        self._queue.put(None)
+        self._thread.join(timeout=3.0)
+
+    def _worker(self) -> None:
+        while True:
+            try:
+                event = self._queue.get(timeout=0.5)
+            except queue.Empty:
+                continue
+
+            if event is None:
+                self._queue.task_done()
+                break
+
+            self._send(event)
+            self._queue.task_done()
+
+    def _send(self, event: dict) -> None:
+        try:
+            response = requests.post(
+                self._config.ingest_url,
+                json=event,
+                headers={
+                    "Authorization": f"Bearer {self._config.api_key}",
+                    "Content-Type": "application/json",
+                    "User-Agent": f"watchdock-errors/{self._config.sdk_version}",
+                },
+                timeout=self._config.timeout,
+            )
+            if response.status_code not in (200, 201, 202):
+                logger.debug("watchdock_errors: ingest returned %s", response.status_code)
+        except Exception:
+            logger.debug("watchdock_errors: failed to send event", exc_info=True)

watchdock_errors/config.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Callable
+
+
+@dataclass
+class SDKConfig:
+    api_key: str
+    endpoint: str = "https://api.watchdock.cc"
+    environment: str = "production"
+    release: str | None = None
+    server_name: str | None = None
+    send_pii: bool = False
+    before_send: Callable[[dict], dict | None] | None = None
+    timeout: float = 1.0
+
+    # Internal — appended to every event payload
+    sdk_name: str = field(default="watchdock-errors", init=False, repr=False)
+    sdk_version: str = field(default="0.1.0", init=False, repr=False)
+
+    @property
+    def ingest_url(self) -> str:
+        base = self.endpoint.rstrip("/")
+        return f"{base}/api/v1/error-events/"

watchdock_errors/event.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+import datetime
+import logging
+
+from .config import SDKConfig
+from .utils import extract_stacktrace, get_server_info
+
+logger = logging.getLogger("watchdock_errors")
+
+
+def build_event(
+    exc: BaseException | None,
+    config: SDKConfig,
+    message: str | None = None,
+    request_context: dict | None = None,
+) -> dict | None:
+    """
+    Build a Watchdock error event payload.
+
+    Returns None if the event should be dropped (e.g., before_send returned None).
+    """
+    now = datetime.datetime.now(datetime.timezone.utc).isoformat()
+
+    if exc is not None:
+        exception_data = {
+            "type": type(exc).__name__,
+            "message": str(exc),
+            "stacktrace": extract_stacktrace(exc),
+        }
+        title = message or f"{type(exc).__name__}: {str(exc)}"
+    else:
+        exception_data = {
+            "type": "Message",
+            "message": message or "",
+            "stacktrace": [],
+        }
+        title = message or ""
+
+    event: dict = {
+        "project_key": config.api_key,
+        "timestamp": now,
+        "environment": config.environment,
+        "title": title,
+        "sdk": {
+            "name": config.sdk_name,
+            "version": config.sdk_version,
+        },
+        "exception": exception_data,
+        "server": get_server_info(),
+    }
+
+    if config.release:
+        event["release"] = config.release
+
+    if config.server_name:
+        event["server"]["server_name"] = config.server_name
+
+    if request_context:
+        if config.send_pii:
+            event["request"] = request_context.get("request", {})
+            event["user"] = request_context.get("user", {})
+        else:
+            req = dict(request_context.get("request", {}))
+            req.pop("body", None)
+            headers = dict(req.get("headers", {}))
+            for sensitive in ("Authorization", "Cookie", "X-Api-Key"):
+                headers.pop(sensitive, None)
+            req["headers"] = headers
+            event["request"] = req
+
+    if config.before_send is not None:
+        try:
+            event = config.before_send(event)
+        except Exception:
+            logger.exception("watchdock_errors: before_send hook raised an exception")
+            return None
+        if event is None:
+            return None
+
+    return event

watchdock_errors/integrations/django.py

@@ -0,0 +1,86 @@
+"""
+Django integration for watchdock-errors.
+
+Option A — INSTALLED_APPS (auto-registers middleware via AppConfig signal):
+    INSTALLED_APPS = [
+        ...
+        "watchdock_errors.integrations.django",
+    ]
+
+Option B — MIDDLEWARE (explicit):
+    MIDDLEWARE = [
+        ...
+        "watchdock_errors.integrations.django.DjangoErrorMiddleware",
+    ]
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import watchdock_errors
+
+if TYPE_CHECKING:
+    from django.http import HttpRequest, HttpResponse
+
+
+class DjangoErrorMiddleware:
+    """
+    Django middleware that captures unhandled exceptions and forwards them
+    to Watchdock without interfering with normal Django error handling.
+    """
+
+    def __init__(self, get_response) -> None:
+        self.get_response = get_response
+
+    def __call__(self, request: "HttpRequest") -> "HttpResponse":
+        try:
+            response = self.get_response(request)
+        except Exception as exc:
+            watchdock_errors.capture_exception(exc, request_context=_build_request_context(request))
+            raise
+        return response
+
+
+def _build_request_context(request: "HttpRequest") -> dict:
+    ctx: dict = {
+        "request": {
+            "method": request.method,
+            "url": request.build_absolute_uri(),
+            "headers": dict(request.headers),
+            "query_params": dict(request.GET),
+        }
+    }
+
+    if hasattr(request, "user") and request.user and request.user.is_authenticated:
+        ctx["user"] = {
+            "id": str(request.user.pk),
+            "email": getattr(request.user, "email", ""),
+        }
+
+    return ctx
+
+
+# AppConfig for INSTALLED_APPS auto-discovery
+try:
+    from django.apps import AppConfig
+
+    class WatchdockErrorsDjangoConfig(AppConfig):
+        name = "watchdock_errors.integrations.django"
+        label = "watchdock_errors_django"
+        verbose_name = "Watchdock Errors"
+
+        def ready(self) -> None:
+            # Auto-inject middleware when added to INSTALLED_APPS.
+            # We patch the middleware list rather than using signals so it works
+            # with both sync and async Django.
+            from django.conf import settings
+
+            middleware_path = "watchdock_errors.integrations.django.DjangoErrorMiddleware"
+            if middleware_path not in settings.MIDDLEWARE:
+                settings.MIDDLEWARE = list(settings.MIDDLEWARE) + [middleware_path]
+
+    default_app_config = "watchdock_errors.integrations.django.WatchdockErrorsDjangoConfig"
+
+except ImportError:
+    pass

watchdock_errors/integrations/fastapi.py

@@ -0,0 +1,68 @@
+"""
+FastAPI / Starlette integration for watchdock-errors.
+
+Usage:
+    from watchdock_errors.integrations.fastapi import setup_watchdock
+
+    setup_watchdock(app)
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import watchdock_errors
+
+if TYPE_CHECKING:
+    from fastapi import FastAPI
+    from starlette.types import ASGIApp, Receive, Scope, Send
+
+
+class WatchdockASGIMiddleware:
+    """ASGI middleware that captures unhandled exceptions."""
+
+    def __init__(self, app: "ASGIApp") -> None:
+        self.app = app
+
+    async def __call__(self, scope: "Scope", receive: "Receive", send: "Send") -> None:
+        if scope["type"] not in ("http", "websocket"):
+            await self.app(scope, receive, send)
+            return
+
+        try:
+            await self.app(scope, receive, send)
+        except Exception as exc:
+            watchdock_errors.capture_exception(exc, request_context=_build_request_context(scope))
+            raise
+
+
+def _build_request_context(scope: dict) -> dict:
+    headers = {k.decode(): v.decode() for k, v in scope.get("headers", [])}
+    query_string = scope.get("query_string", b"").decode()
+
+    return {
+        "request": {
+            "method": scope.get("method", ""),
+            "url": _build_url(scope),
+            "headers": headers,
+            "query_params": query_string,
+        }
+    }
+
+
+def _build_url(scope: dict) -> str:
+    scheme = scope.get("scheme", "http")
+    server = scope.get("server")
+    host = f"{server[0]}:{server[1]}" if server else "localhost"
+    path = scope.get("path", "/")
+    query = scope.get("query_string", b"").decode()
+    return f"{scheme}://{host}{path}{'?' + query if query else ''}"
+
+
+def setup_watchdock(app: "FastAPI") -> None:
+    """
+    Install the Watchdock ASGI error-capture middleware on a FastAPI app.
+
+    Call this after ``watchdock_errors.init()`` and before adding other middleware.
+    """
+    app.add_middleware(WatchdockASGIMiddleware)

watchdock_errors/utils.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+import linecache
+import platform
+import socket
+import traceback
+
+
+def extract_stacktrace(exc: BaseException) -> list[dict]:
+    """Extract structured stack frames from an exception."""
+    tb = exc.__traceback__
+    if tb is None:
+        return []
+
+    frames = []
+    for frame_summary in traceback.extract_tb(tb):
+        context_line = linecache.getline(frame_summary.filename, frame_summary.lineno).strip()
+        frames.append(
+            {
+                "filename": frame_summary.filename,
+                "function": frame_summary.name,
+                "lineno": frame_summary.lineno,
+                "context_line": context_line,
+            }
+        )
+    return frames
+
+
+def get_server_info() -> dict:
+    return {
+        "hostname": socket.gethostname(),
+        "python_version": platform.python_version(),
+    }

watchdock_errors-0.1.0.dist-info/METADATA

@@ -0,0 +1,104 @@
+Metadata-Version: 2.4
+Name: watchdock-errors
+Version: 0.1.0
+Summary: Application error tracking SDK for the Watchdock platform
+License: MIT
+Keywords: error-tracking,observability,watchdock
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.28
+Provides-Extra: django
+Requires-Dist: django>=3.2; extra == "django"
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.95; extra == "fastapi"
+Requires-Dist: starlette>=0.27; extra == "fastapi"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.0; extra == "dev"
+Requires-Dist: responses>=0.23; extra == "dev"
+
+# watchdock-errors
+
+Python SDK for application-level error tracking on the [Watchdock](https://watchdock.cc) platform.
+
+## Installation
+
+```bash
+pip install watchdock-errors
+```
+
+With framework extras:
+
+```bash
+pip install "watchdock-errors[django]"
+pip install "watchdock-errors[fastapi]"
+```
+
+## Quickstart
+
+```python
+import watchdock_errors
+
+watchdock_errors.init(
+    api_key="wdk_xxx",
+    environment="production",
+    release="1.0.0",
+)
+```
+
+### Django
+
+```python
+# settings.py
+MIDDLEWARE = [
+    ...
+    "watchdock_errors.integrations.django.DjangoErrorMiddleware",
+]
+```
+
+Or via `INSTALLED_APPS` for automatic registration:
+
+```python
+INSTALLED_APPS = [
+    ...
+    "watchdock_errors.integrations.django",
+]
+```
+
+### FastAPI
+
+```python
+from watchdock_errors.integrations.fastapi import setup_watchdock
+
+setup_watchdock(app)
+```
+
+## Manual capture
+
+```python
+# Capture the current exception
+try:
+    process_payment()
+except Exception:
+    watchdock_errors.capture_exception()
+
+# Capture a specific exception
+watchdock_errors.capture_exception(exc)
+
+# Capture a message
+watchdock_errors.capture_message("Stripe webhook signature invalid")
+```
+
+## PII scrubbing
+
+By default, `Authorization`, `Cookie`, and `X-Api-Key` headers are stripped and the request body is not sent. Set `send_pii=True` to disable scrubbing.
+
+Use the `before_send` hook for custom scrubbing:
+
+```python
+def scrub(event):
+    event["request"]["headers"].pop("X-Internal-Token", None)
+    return event  # return None to drop the event entirely
+
+watchdock_errors.init(api_key="wdk_xxx", before_send=scrub)
+```

watchdock_errors-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+watchdock_errors/__init__.py,sha256=zEgpAJ1FiiPoTUEkFTMN_QczkziUIvnGz9PcH6cLmjw,3229
+watchdock_errors/client.py,sha256=CkuNEIpjKU6TLp8dauShuT3DM1iuxMHiFkO8PE5hhyM,2485
+watchdock_errors/config.py,sha256=Ownx85BnuN-jdzlNiBqjUWKMiSnjC1gIkZxoanTxOHI,774
+watchdock_errors/event.py,sha256=sagnYKrqNQSAYoWs6_KBH5h0mD45CIRyuFGBY2ceTZA,2405
+watchdock_errors/utils.py,sha256=upQCS9KSbmJo32emhEDduu2lKceJBcSBTEJDgQ-v2A0,901
+watchdock_errors/integrations/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+watchdock_errors/integrations/django.py,sha256=yjq0oSLScRe2kr2G3V1RF7tM6tzBe8X1nL0rwsSjYjk,2644
+watchdock_errors/integrations/fastapi.py,sha256=Nf2RMtQV-inDMDsARYdXXQAAvy_65W-lhX9V6WFqahE,2031
+watchdock_errors-0.1.0.dist-info/METADATA,sha256=AzXEK2uaAAB02yFS6YQn9ji2stxCoRCM_FWMFsfV6d4,2326
+watchdock_errors-0.1.0.dist-info/WHEEL,sha256=YCfwYGOYMi5Jhw2fU4yNgwErybb2IX5PEwBKV4ZbdBo,91
+watchdock_errors-0.1.0.dist-info/top_level.txt,sha256=3HlgohNEtJG4IQb8p5jLkK046xW47MeIR-RU8N95H0M,17
+watchdock_errors-0.1.0.dist-info/RECORD,,

watchdock_errors-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

watchdock_errors-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+watchdock_errors