steadwing 0.1.0__py3-none-any.whl

steadwing/__init__.py

@@ -0,0 +1,42 @@
+"""Steadwing Python SDK — auto-captures exceptions, error logs, and HTTP breadcrumbs."""
+
+from __future__ import annotations
+
+from steadwing.client import SteadwingClient
+from steadwing.types import SDK_VERSION
+
+__version__ = SDK_VERSION
+
+
+def init(
+    api_key: str,
+    service: str,
+    env: str = "PROD",
+    enabled: bool = True,
+) -> SteadwingClient:
+    """Initialize the Steadwing SDK.
+
+    Idempotent — returns existing client if already initialized.
+    Pure auto-capture: no manual API needed after init.
+
+    Args:
+        api_key: Your Steadwing API key (e.g. "st_...").
+        service: Name of your service (e.g. "payment-service").
+        env: Deployment environment (e.g. "PROD", "DEV").
+        enabled: Whether to enable capture (default True). Set False to disable.
+
+    Returns:
+        The initialized SteadwingClient instance.
+    """
+    existing = SteadwingClient.get_instance()
+    if existing is not None:
+        return existing
+
+    client = SteadwingClient(
+        api_key=api_key,
+        service=service,
+        env=env,
+        enabled=enabled,
+    )
+    SteadwingClient.set_instance(client)
+    return client

steadwing/breadcrumbs.py

@@ -0,0 +1,169 @@
+"""HTTP breadcrumb capture via http.client monkey-patching."""
+
+from __future__ import annotations
+
+import http.client
+import threading
+import time
+from collections import deque
+from typing import Any
+
+_breadcrumbs: deque[dict[str, Any]] = deque(maxlen=100)
+_lock = threading.Lock()
+_original_http_request: Any = None
+_original_https_request: Any = None
+_original_http_getresponse: Any = None
+_original_https_getresponse: Any = None
+_patched = False
+_in_sdk_call = threading.local()
+
+
+def get_breadcrumbs() -> list[dict[str, Any]]:
+    """Return a copy of the current breadcrumbs."""
+    with _lock:
+        return list(_breadcrumbs)
+
+
+def clear_breadcrumbs() -> None:
+    """Clear all breadcrumbs."""
+    with _lock:
+        _breadcrumbs.clear()
+
+
+def add_breadcrumb(breadcrumb: dict[str, Any]) -> None:
+    """Add a breadcrumb to the rolling buffer."""
+    with _lock:
+        _breadcrumbs.append(breadcrumb)
+
+
+def mark_sdk_call():
+    """Mark current thread as making an SDK-internal HTTP call (skip breadcrumb)."""
+    _in_sdk_call.active = True
+
+
+def unmark_sdk_call():
+    """Unmark current thread."""
+    _in_sdk_call.active = False
+
+
+def _patched_request(original_fn: Any):
+    """Create a patched request function that records HTTP breadcrumbs."""
+
+    def wrapper(self: Any, method: str, url: str, body: Any = None, headers: Any = None, **kwargs: Any) -> Any:
+        if headers is None:
+            headers = {}
+        if getattr(_in_sdk_call, "active", False):
+            return original_fn(self, method, url, body=body, headers=headers, **kwargs)
+        start = time.time()
+        try:
+            result = original_fn(self, method, url, body=body, headers=headers, **kwargs)
+            duration_ms = (time.time() - start) * 1000
+            breadcrumb = {
+                "type": "http",
+                "timestamp": start,
+                "data": {
+                    "method": method,
+                    "url": f"{self.host}{url}",
+                    "duration_ms": round(duration_ms, 2),
+                },
+            }
+            # Stash the breadcrumb on the connection so the matching
+            # getresponse() call can fill in the status code.
+            try:
+                self._steadwing_breadcrumb = breadcrumb
+            except Exception:
+                pass
+            add_breadcrumb(breadcrumb)
+            return result
+        except Exception as exc:
+            duration_ms = (time.time() - start) * 1000
+            add_breadcrumb({
+                "type": "http",
+                "timestamp": start,
+                "data": {
+                    "method": method,
+                    "url": f"{self.host}{url}",
+                    "duration_ms": round(duration_ms, 2),
+                    "error": repr(exc)[:256],
+                },
+            })
+            raise
+
+    return wrapper
+
+
+def _patched_getresponse(original_fn: Any):
+    """Create a patched getresponse that records the HTTP status code."""
+
+    def wrapper(self: Any, *args: Any, **kwargs: Any) -> Any:
+        response = original_fn(self, *args, **kwargs)
+        try:
+            breadcrumb = getattr(self, "_steadwing_breadcrumb", None)
+            if breadcrumb is not None:
+                status = getattr(response, "status", None)
+                if status is not None:
+                    breadcrumb["data"]["status_code"] = status
+                self._steadwing_breadcrumb = None
+        except Exception:
+            pass
+        return response
+
+    return wrapper
+
+
+def patch_http_client() -> None:
+    """Monkey-patch http.client to capture outgoing HTTP requests as breadcrumbs."""
+    global _original_http_request, _original_https_request, _patched
+    global _original_http_getresponse, _original_https_getresponse
+
+    if _patched:
+        return
+
+    try:
+        _original_http_request = http.client.HTTPConnection.request
+        http.client.HTTPConnection.request = _patched_request(_original_http_request)
+        _original_http_getresponse = http.client.HTTPConnection.getresponse
+        http.client.HTTPConnection.getresponse = _patched_getresponse(_original_http_getresponse)
+
+        # HTTPSConnection normally inherits request/getresponse from HTTPConnection,
+        # so the patches above already cover HTTPS. Only patch it separately on the
+        # (rare) Python builds where it defines its own — patching inherited methods
+        # again would double-wrap and emit two breadcrumbs per HTTPS request.
+        https_conn = getattr(http.client, "HTTPSConnection", None)
+        if https_conn is not None:
+            if "request" in https_conn.__dict__:
+                _original_https_request = https_conn.request
+                https_conn.request = _patched_request(_original_https_request)
+            if "getresponse" in https_conn.__dict__:
+                _original_https_getresponse = https_conn.getresponse
+                https_conn.getresponse = _patched_getresponse(_original_https_getresponse)
+
+        _patched = True
+    except Exception:
+        pass
+
+
+def unpatch_http_client() -> None:
+    """Restore original http.client methods."""
+    global _original_http_request, _original_https_request, _patched
+    global _original_http_getresponse, _original_https_getresponse
+
+    if not _patched:
+        return
+
+    try:
+        if _original_http_request is not None:
+            http.client.HTTPConnection.request = _original_http_request
+        if _original_http_getresponse is not None:
+            http.client.HTTPConnection.getresponse = _original_http_getresponse
+
+        https_conn = getattr(http.client, "HTTPSConnection", None)
+        if https_conn is not None:
+            if _original_https_request is not None:
+                https_conn.request = _original_https_request
+            if _original_https_getresponse is not None:
+                https_conn.getresponse = _original_https_getresponse
+
+        _patched = False
+    except Exception:
+        pass

steadwing/client.py

@@ -0,0 +1,215 @@
+"""Main SteadwingClient class — singleton that orchestrates all SDK functionality."""
+
+from __future__ import annotations
+
+import atexit
+import os
+import signal
+import threading
+from typing import Any
+
+from steadwing.breadcrumbs import patch_http_client
+from steadwing.hooks import patch_hooks
+from steadwing.integrations.asyncio_hook import patch_asyncio
+from steadwing.logging_handler import install_logging_handler
+from steadwing.transport import Transport
+from steadwing.types import base_event, build_runtime_info
+
+_DEFAULT_BACKEND_URL = "https://api.steadwing.com"
+_HEARTBEAT_INTERVAL = 60.0
+
+
+class SteadwingClient:
+    """Core SDK client that manages patching, event capture, and transport."""
+
+    _instance: SteadwingClient | None = None
+    _init_lock = threading.Lock()
+
+    def __init__(
+        self,
+        api_key: str,
+        service: str,
+        env: str = "PROD",
+        enabled: bool = True,
+    ):
+        self.api_key = api_key
+        self.service = service
+        self.env = env
+        self.enabled = enabled
+        self.backend_url = os.environ.get("STEADWING_BACKEND_URL", _DEFAULT_BACKEND_URL)
+        self.runtime = build_runtime_info()
+        self._transport: Transport | None = None
+        self._heartbeat_timer: threading.Timer | None = None
+        self._shutdown = False
+
+        if self.enabled:
+            self._setup()
+
+    def _setup(self) -> None:
+        """Set up transport, patches, and heartbeat."""
+        # Start transport
+        self._transport = Transport(api_key=self.api_key, backend_url=self.backend_url)
+        self._transport.start()
+
+        # Install exception hooks
+        patch_hooks(on_exception=self._handle_exception)
+
+        # Install logging handler
+        install_logging_handler(on_log_event=self._handle_log_event)
+
+        # Patch http.client for breadcrumbs
+        patch_http_client()
+
+        # Capture unhandled errors from asyncio tasks / event loop
+        patch_asyncio(on_exception=self._handle_exception)
+
+        # Auto-detect and patch supported frameworks
+        self._try_patch_frameworks()
+
+        # Start heartbeat
+        self._start_heartbeat()
+
+        # Register shutdown handlers (atexit + SIGTERM for containers)
+        atexit.register(self._atexit_handler)
+        try:
+            signal.signal(signal.SIGTERM, lambda *_: self._atexit_handler())
+        except (OSError, ValueError):
+            pass
+
+    def _try_patch_frameworks(self) -> None:
+        """Auto-detect and patch supported frameworks and DB libraries."""
+        # FastAPI
+        try:
+            import fastapi  # noqa: F401
+
+            from steadwing.integrations.fastapi import patch_fastapi
+
+            patch_fastapi(on_exception=self._handle_exception)
+        except ImportError:
+            pass
+        except Exception:
+            pass
+
+        # Django
+        try:
+            import django  # noqa: F401
+
+            from steadwing.integrations.django import patch_django
+
+            patch_django(on_exception=self._handle_exception)
+        except ImportError:
+            pass
+        except Exception:
+            pass
+
+        # Django DB (query breadcrumbs)
+        try:
+            from django.db.backends.utils import CursorWrapper  # noqa: F401
+
+            from steadwing.integrations.django_db import patch_django_db
+
+            patch_django_db()
+        except ImportError:
+            pass
+        except Exception:
+            pass
+
+        # Flask
+        try:
+            import flask  # noqa: F401
+
+            from steadwing.integrations.flask import patch_flask
+
+            patch_flask(on_exception=self._handle_exception)
+        except ImportError:
+            pass
+        except Exception:
+            pass
+
+        # SQLAlchemy (query breadcrumbs)
+        try:
+            import sqlalchemy  # noqa: F401
+
+            from steadwing.integrations.sqlalchemy import patch_sqlalchemy
+
+            patch_sqlalchemy()
+        except ImportError:
+            pass
+        except Exception:
+            pass
+
+    def _handle_exception(self, event_data: dict[str, Any], flush: bool = False) -> None:
+        """Handle a captured exception event.
+
+        Args:
+            event_data: The exception event payload.
+            flush: If True (uncaught/thread/async errors that kill the process),
+                flush the transport synchronously so the event isn't lost.
+        """
+        if not self.enabled or self._transport is None:
+            return
+
+        try:
+            event = base_event("exception", self.service, self.env, self.runtime)
+            event.update(event_data)
+            self._transport.enqueue(event)
+            if flush:
+                self._transport.flush_sync()
+        except Exception:
+            pass
+
+    def _handle_log_event(self, log_data: dict[str, Any]) -> None:
+        """Handle a captured log event."""
+        if not self.enabled or self._transport is None:
+            return
+
+        try:
+            event = base_event("log", self.service, self.env, self.runtime)
+            event.update(log_data)
+            self._transport.enqueue(event)
+        except Exception:
+            pass
+
+    def _start_heartbeat(self) -> None:
+        """Start the recurring heartbeat timer."""
+        if self._shutdown:
+            return
+
+        def heartbeat() -> None:
+            if self._shutdown:
+                return
+            try:
+                event = base_event("heartbeat", self.service, self.env, self.runtime)
+                event["status"] = "healthy"
+                if self._transport is not None:
+                    self._transport.enqueue(event)
+            except Exception:
+                pass
+            # Reschedule
+            if not self._shutdown:
+                self._heartbeat_timer = threading.Timer(_HEARTBEAT_INTERVAL, heartbeat)
+                self._heartbeat_timer.daemon = True
+                self._heartbeat_timer.start()
+
+        self._heartbeat_timer = threading.Timer(_HEARTBEAT_INTERVAL, heartbeat)
+        self._heartbeat_timer.daemon = True
+        self._heartbeat_timer.start()
+
+    def _atexit_handler(self) -> None:
+        """Flush remaining events on process exit."""
+        self._shutdown = True
+        if self._heartbeat_timer is not None:
+            self._heartbeat_timer.cancel()
+        if self._transport is not None:
+            self._transport.shutdown()
+
+    @classmethod
+    def get_instance(cls) -> SteadwingClient | None:
+        """Get the singleton instance."""
+        return cls._instance
+
+    @classmethod
+    def set_instance(cls, instance: SteadwingClient) -> None:
+        """Set the singleton instance."""
+        with cls._init_lock:
+            cls._instance = instance

steadwing/hooks.py

@@ -0,0 +1,172 @@
+"""Exception hooks for sys.excepthook and threading patches."""
+
+from __future__ import annotations
+
+import sys
+import threading
+import traceback
+from typing import Any
+
+from steadwing.breadcrumbs import get_breadcrumbs
+from steadwing.scrubber import scrub
+
+_original_excepthook: Any = None
+_original_thread_run: Any = None
+_patched = False
+_on_exception_callback: Any = None
+
+MAX_LOCAL_VAR_LENGTH = 1024
+MAX_STACK_FRAMES = 50
+
+
+def _extract_locals(tb: Any) -> list[dict[str, Any]]:
+    """Extract local variables from traceback frames."""
+    frames = []
+    current = tb
+    while current is not None:
+        try:
+            frame = current.tb_frame
+            local_vars = {}
+            for key, value in frame.f_locals.items():
+                if key.startswith("__"):
+                    continue
+                try:
+                    val_repr = repr(value)
+                    if len(val_repr) > MAX_LOCAL_VAR_LENGTH:
+                        val_repr = val_repr[:MAX_LOCAL_VAR_LENGTH] + "..."
+                    local_vars[key] = val_repr
+                except Exception:
+                    local_vars[key] = "<unrepresentable>"
+            frames.append({
+                "filename": frame.f_code.co_filename,
+                "lineno": current.tb_lineno,
+                "function": frame.f_code.co_name,
+                "locals": scrub(local_vars),
+            })
+        except Exception:
+            pass
+        current = current.tb_next
+    return frames
+
+
+def _extract_exception_chain(exc: BaseException) -> list[dict[str, Any]]:
+    """Extract the exception chain (__cause__ and __context__)."""
+    chain = []
+    seen: set[int] = set()
+    current: BaseException | None = exc
+
+    while current is not None and id(current) not in seen:
+        seen.add(id(current))
+        chain.append({
+            "type": type(current).__name__,
+            "module": type(current).__module__,
+            "message": str(current),
+        })
+        # Follow __cause__ first, then __context__
+        if current.__cause__ is not None:
+            current = current.__cause__
+        elif current.__context__ is not None and not current.__suppress_context__:
+            current = current.__context__
+        else:
+            current = None
+
+    return chain
+
+
+def build_exception_event(
+    exc_type: type,
+    exc_value: BaseException,
+    exc_tb: Any,
+) -> dict[str, Any]:
+    """Build an exception event payload."""
+    frames = _extract_locals(exc_tb) if exc_tb else []
+    if len(frames) > MAX_STACK_FRAMES:
+        frames = frames[-MAX_STACK_FRAMES:]
+    tb_str = "".join(traceback.format_exception(exc_type, exc_value, exc_tb))
+
+    return {
+        "exception_type": exc_type.__name__,
+        "exception_module": exc_type.__module__,
+        "exception_message": str(exc_value),
+        "traceback": tb_str,
+        "frames": frames,
+        "exception_chain": _extract_exception_chain(exc_value),
+        "breadcrumbs": get_breadcrumbs(),
+    }
+
+
+def _steadwing_excepthook(exc_type: type, exc_value: BaseException, exc_tb: Any) -> None:
+    """Custom excepthook that captures exceptions then calls the original."""
+    try:
+        if _on_exception_callback is not None:
+            event_data = build_exception_event(exc_type, exc_value, exc_tb)
+            # Uncaught exception → process is about to die. Flush synchronously
+            # so startup/boot crashes still reach the backend.
+            _on_exception_callback(event_data, flush=True)
+    except Exception:
+        pass
+
+    # Always call the original excepthook
+    if _original_excepthook is not None:
+        _original_excepthook(exc_type, exc_value, exc_tb)
+
+
+def _patched_thread_run(self: threading.Thread) -> None:
+    """Patched Thread.run that captures exceptions in threads."""
+    try:
+        if _original_thread_run is not None:
+            _original_thread_run(self)
+    except Exception:
+        try:
+            if _on_exception_callback is not None:
+                exc_type, exc_value, exc_tb = sys.exc_info()
+                if exc_type is not None:
+                    event_data = build_exception_event(exc_type, exc_value, exc_tb)
+                    # Thread is dying from this exception — flush before re-raise.
+                    _on_exception_callback(event_data, flush=True)
+        except Exception:
+            pass
+        raise
+
+
+def patch_hooks(on_exception: Any) -> None:
+    """Install exception hooks.
+
+    Args:
+        on_exception: Callback function that receives exception event data dict.
+    """
+    global _original_excepthook, _original_thread_run, _patched, _on_exception_callback
+
+    if _patched:
+        return
+
+    _on_exception_callback = on_exception
+
+    try:
+        _original_excepthook = sys.excepthook
+        sys.excepthook = _steadwing_excepthook
+
+        _original_thread_run = threading.Thread.run
+        threading.Thread.run = _patched_thread_run
+
+        _patched = True
+    except Exception:
+        pass
+
+
+def unpatch_hooks() -> None:
+    """Restore original exception hooks."""
+    global _original_excepthook, _original_thread_run, _patched, _on_exception_callback
+
+    if not _patched:
+        return
+
+    try:
+        if _original_excepthook is not None:
+            sys.excepthook = _original_excepthook
+        if _original_thread_run is not None:
+            threading.Thread.run = _original_thread_run
+        _patched = False
+        _on_exception_callback = None
+    except Exception:
+        pass

steadwing/integrations/__init__.py

@@ -0,0 +1 @@
+"""Steadwing framework integrations."""

steadwing/integrations/asyncio_hook.py

@@ -0,0 +1,78 @@
+"""Asyncio integration: capture unhandled exceptions from tasks and the event loop.
+
+Errors raised inside `async def` handlers, `create_task()`, `gather()`, and other
+coroutines that are never awaited surface through the event loop's exception
+handler rather than `sys.excepthook`. This module installs a handler on the
+running loop (if any) and patches loop creation so future loops are covered too.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+
+from steadwing.hooks import build_exception_event
+
+_patched = False
+
+
+def _make_handler(on_exception: Any, previous: Any) -> Any:
+    """Wrap an event-loop exception handler so captured errors are forwarded."""
+
+    def handler(loop: Any, context: dict[str, Any]) -> None:
+        exc = context.get("exception")
+        if exc is not None:
+            try:
+                event_data = build_exception_event(type(exc), exc, exc.__traceback__)
+                # Unhandled async errors are fatal-ish — flush immediately.
+                on_exception(event_data, flush=True)
+            except Exception:
+                pass
+        # Preserve prior behavior (logging the error, etc.)
+        try:
+            if previous is not None:
+                previous(loop, context)
+            else:
+                loop.default_exception_handler(context)
+        except Exception:
+            pass
+
+    return handler
+
+
+def patch_asyncio(on_exception: Any) -> None:
+    """Install an asyncio exception handler on the current and future event loops.
+
+    Args:
+        on_exception: Callback ``(event_data: dict, flush: bool)`` invoked per error.
+    """
+    global _patched
+
+    if _patched:
+        return
+
+    try:
+        # Cover a loop that is already running (init() called from async context).
+        try:
+            running = asyncio.get_running_loop()
+            running.set_exception_handler(_make_handler(on_exception, running.get_exception_handler()))
+        except RuntimeError:
+            pass
+
+        # Cover loops created later (the common case: init() runs before the
+        # server starts its loop).
+        _original_new = asyncio.new_event_loop
+
+        def _patched_new() -> Any:
+            loop = _original_new()
+            try:
+                loop.set_exception_handler(_make_handler(on_exception, None))
+            except Exception:
+                pass
+            return loop
+
+        asyncio.new_event_loop = _patched_new
+
+        _patched = True
+    except Exception:
+        pass