insider-python 0.1.4__tar.gz → 0.1.5__tar.gz

{insider_python-0.1.4 → insider_python-0.1.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: insider-python
-Version: 0.1.4
+Version: 0.1.5
 Summary: Python SDK for Insider — ship Beacons to your Insider server.
 Author: Insider
 License-Expression: MIT
@@ -70,7 +70,10 @@ Out-of-band events (background jobs, explicit calls) use standalone beacons:
 
 ### Django
 
-Initialize in `wsgi.py` (or `asgi.py`) before `get_wsgi_application()`:
+Initialize in `wsgi.py` or `asgi.py` **before** `get_wsgi_application()` /
+`get_asgi_application()`:
+
+#### WSGI (Gunicorn)
 
 ```python
 import os
@@ -78,6 +81,8 @@ import insider
 from insider.integrations.django import DjangoIntegration
 from insider.integrations.logging import LoggingIntegration
 
+os.environ.setdefault("DJANGO_SETTINGS_MODULE", "myproject.settings")
+
 insider.init(
     dsn=os.environ.get("INSIDER_DSN"),
     environment="production",
@@ -90,6 +95,65 @@ from django.core.wsgi import get_wsgi_application
 application = get_wsgi_application()
 ```
 
+#### ASGI (Daphne / Uvicorn — plain Django)
+
+```python
+import os
+import insider
+from insider.integrations.django import DjangoIntegration
+from insider.integrations.logging import LoggingIntegration
+
+os.environ.setdefault("DJANGO_SETTINGS_MODULE", "myproject.settings")
+
+insider.init(
+    dsn=os.environ.get("INSIDER_DSN"),
+    environment="production",
+    release="1.2.3",
+    enable_logs=True,
+    integrations=[DjangoIntegration(), LoggingIntegration()],
+)
+
+from django.core.asgi import get_asgi_application
+application = get_asgi_application()
+```
+
+#### ASGI + Channels (`ProtocolTypeRouter`)
+
+Wrap only the HTTP branch; disable handler auto-perf to avoid double capture:
+
+```python
+import os
+import django
+
+os.environ.setdefault("DJANGO_SETTINGS_MODULE", "myproject.settings")
+
+import django
+
+django.setup()
+
+import insider
+from insider.integrations.django import DjangoIntegration
+from insider.integrations.django.asgi import wrap_asgi_application
+from insider.integrations.logging import LoggingIntegration
+
+insider.init(
+    dsn=os.environ.get("INSIDER_DSN"),
+    environment="production",
+    enable_logs=True,
+    integrations=[DjangoIntegration(auto_perf=False), LoggingIntegration()],
+)
+
+from channels.routing import ProtocolTypeRouter, URLRouter
+from django.core.asgi import get_asgi_application
+
+application = ProtocolTypeRouter({
+    "http": wrap_asgi_application(get_asgi_application()),
+    "websocket": URLRouter(websocket_urlpatterns),
+})
+```
+
+Set `INSIDER_DEBUG=true` to print which hooks installed at startup.
+
 That's the whole setup. **Every HTTP request** emits **one** `kind=request`
 beacon containing:
 

{insider_python-0.1.4 → insider_python-0.1.5}/README.md

@@ -42,7 +42,10 @@ Out-of-band events (background jobs, explicit calls) use standalone beacons:
 
 ### Django
 
-Initialize in `wsgi.py` (or `asgi.py`) before `get_wsgi_application()`:
+Initialize in `wsgi.py` or `asgi.py` **before** `get_wsgi_application()` /
+`get_asgi_application()`:
+
+#### WSGI (Gunicorn)
 
 ```python
 import os
@@ -50,6 +53,8 @@ import insider
 from insider.integrations.django import DjangoIntegration
 from insider.integrations.logging import LoggingIntegration
 
+os.environ.setdefault("DJANGO_SETTINGS_MODULE", "myproject.settings")
+
 insider.init(
     dsn=os.environ.get("INSIDER_DSN"),
     environment="production",
@@ -62,6 +67,65 @@ from django.core.wsgi import get_wsgi_application
 application = get_wsgi_application()
 ```
 
+#### ASGI (Daphne / Uvicorn — plain Django)
+
+```python
+import os
+import insider
+from insider.integrations.django import DjangoIntegration
+from insider.integrations.logging import LoggingIntegration
+
+os.environ.setdefault("DJANGO_SETTINGS_MODULE", "myproject.settings")
+
+insider.init(
+    dsn=os.environ.get("INSIDER_DSN"),
+    environment="production",
+    release="1.2.3",
+    enable_logs=True,
+    integrations=[DjangoIntegration(), LoggingIntegration()],
+)
+
+from django.core.asgi import get_asgi_application
+application = get_asgi_application()
+```
+
+#### ASGI + Channels (`ProtocolTypeRouter`)
+
+Wrap only the HTTP branch; disable handler auto-perf to avoid double capture:
+
+```python
+import os
+import django
+
+os.environ.setdefault("DJANGO_SETTINGS_MODULE", "myproject.settings")
+
+import django
+
+django.setup()
+
+import insider
+from insider.integrations.django import DjangoIntegration
+from insider.integrations.django.asgi import wrap_asgi_application
+from insider.integrations.logging import LoggingIntegration
+
+insider.init(
+    dsn=os.environ.get("INSIDER_DSN"),
+    environment="production",
+    enable_logs=True,
+    integrations=[DjangoIntegration(auto_perf=False), LoggingIntegration()],
+)
+
+from channels.routing import ProtocolTypeRouter, URLRouter
+from django.core.asgi import get_asgi_application
+
+application = ProtocolTypeRouter({
+    "http": wrap_asgi_application(get_asgi_application()),
+    "websocket": URLRouter(websocket_urlpatterns),
+})
+```
+
+Set `INSIDER_DEBUG=true` to print which hooks installed at startup.
+
 That's the whole setup. **Every HTTP request** emits **one** `kind=request`
 beacon containing:
 

{insider_python-0.1.4 → insider_python-0.1.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "insider-python"
-version = "0.1.4"
+version = "0.1.5"
 description = "Python SDK for Insider — ship Beacons to your Insider server."
 readme = "README.md"
 requires-python = ">=3.8"

{insider_python-0.1.4 → insider_python-0.1.5}/src/insider/_version.py

@@ -5,4 +5,4 @@ lookup on every beacon. Bump this and `[project].version` together when
 cutting a release.
 """
 
-__version__ = "0.1.4"
+__version__ = "0.1.5"

insider_python-0.1.5/src/insider/integrations/django/__init__.py

@@ -0,0 +1,121 @@
+"""
+Sentry-style Django integration.
+
+Install with `insider.init(..., integrations=[DjangoIntegration()])` in
+`wsgi.py` / `asgi.py` before `get_wsgi_application()` or
+`get_asgi_application()`. No middleware or `INSTALLED_APPS` wiring required.
+
+Hooks installed (each once per process):
+
+  - `got_request_exception` → auto-capture unhandled view errors
+  - `BaseHandler.get_response` → request context on the SDK scope (WSGI + ASGI HTTP)
+  - `WSGIHandler.__call__` → capture catastrophic WSGI escapes
+  - `ASGIHandler.__call__` → capture catastrophic ASGI escapes
+  - `APIView.initial` (when DRF is present) → DRF request body access
+  - Auto `kind=request` beacon per HTTP request (optional, default on)
+
+Channels / `ProtocolTypeRouter`: use `wrap_asgi_application()` on the HTTP
+branch with `DjangoIntegration(auto_perf=False)` — see `asgi.py`.
+"""
+
+from __future__ import annotations
+
+import threading
+from typing import Any, Dict
+
+from ...safety import debug
+from . import asgi, drf, handler, signals, wsgi
+
+
+class DjangoIntegration:
+    """Patch Django's request/exception path — one request beacon per HTTP cycle."""
+
+    identifier = "django"
+
+    _lock = threading.Lock()
+    _installed = False
+
+    def __init__(self, *, auto_perf: bool = True) -> None:
+        """
+        Args:
+            auto_perf: When True (default), emit one `kind=request` beacon
+                after every HTTP request via the `get_response` patch.
+                Set False when using `wrap_asgi_application()` on the HTTP
+                branch of a Channels router (avoids double capture).
+        """
+        self.auto_perf = auto_perf
+
+    def setup_once(self) -> None:
+        cls = type(self)
+        with cls._lock:
+            if cls._installed:
+                return
+
+        try:
+            import django  # noqa: F401
+        except ImportError:
+            debug("DjangoIntegration: django is not installed")
+            return
+
+        # Patch get_response first. Optional hooks below must not block this.
+        handler.install(auto_perf=self.auto_perf)
+        if not handler._patched:
+            debug(
+                "DjangoIntegration: get_response patch failed — "
+                "call insider.init() before get_wsgi_application() / "
+                "get_asgi_application()"
+            )
+            return
+
+        with cls._lock:
+            cls._installed = True
+
+        for label, install in (
+            ("signals", signals.install),
+            ("wsgi", wsgi.install),
+            ("asgi", asgi.install),
+            ("drf", drf.install),
+        ):
+            try:
+                install()
+            except Exception as exc:
+                debug(f"DjangoIntegration: {label} hook failed: {exc}")
+
+        _log_integration_status()
+
+    @classmethod
+    def reset_for_tests(cls) -> None:
+        """Test helper — allow `setup_once()` to run again in the same process."""
+        with cls._lock:
+            cls._installed = False
+
+
+def get_integration_status() -> Dict[str, Any]:
+    """Return which Django hooks are active in this process (tests + debug)."""
+    return {
+        "handler": handler._patched,
+        "handler_auto_perf": handler._auto_perf,
+        "wsgi": wsgi._patched,
+        "asgi_handler": asgi._handler_patched,
+        "signals": signals._connected,
+        "response_for_exception": signals._rfe_patched,
+        "drf": drf._patched,
+    }
+
+
+def _log_integration_status() -> None:
+    status = get_integration_status()
+    debug(
+        "DjangoIntegration: "
+        + ", ".join(f"{key}={value}" for key, value in status.items())
+    )
+
+
+__all__ = [
+    "DjangoIntegration",
+    "get_integration_status",
+    "wrap_asgi_application",
+]
+
+# Re-export for `from insider.integrations.django.asgi import ...`
+from .asgi import wrap_asgi_application  # noqa: E402

insider_python-0.1.5/src/insider/integrations/django/asgi.py

@@ -0,0 +1,123 @@
+"""
+ASGI support for Django — escape capture and optional HTTP wrapper.
+
+`install()` patches `ASGIHandler` (mirrors `wsgi.install()`).
+
+`wrap_asgi_application()` wraps the HTTP branch of a Channels
+`ProtocolTypeRouter` (or plain `get_asgi_application()`). Use with
+`DjangoIntegration(auto_perf=False)` so footprints are not emitted twice.
+"""
+
+from __future__ import annotations
+
+import time
+import uuid
+from typing import Any, Callable, Dict, MutableMapping, Optional
+
+from ... import capture_exception
+from ...client import _client
+from ...safety import debug, safe
+from ...stacktrace import exception_payload
+from .perf import emit_http_footprint
+from .request import build_request_ctx_from_scope
+
+ASGIApp = Callable[..., Any]
+
+_handler_patched = False
+
+
+def install() -> None:
+    """Patch ASGIHandler to capture exceptions that escape Django entirely."""
+    global _handler_patched
+    if _handler_patched:
+        return
+    try:
+        from django.core.handlers.asgi import ASGIHandler
+    except ImportError:
+        debug("django ASGIHandler unavailable; skipping ASGI patch")
+        return
+
+    old_call = ASGIHandler.__call__
+
+    @safe
+    async def patched_call(
+        self: Any,
+        scope: MutableMapping[str, Any],
+        receive: Callable[..., Any],
+        send: Callable[..., Any],
+    ) -> Any:
+        if _client() is None:
+            return await old_call(self, scope, receive, send)
+        try:
+            return await old_call(self, scope, receive, send)
+        except BaseException as exc:
+            capture_exception(exc)
+            raise
+
+    ASGIHandler.__call__ = patched_call  # type: ignore[method-assign]
+    _handler_patched = True
+
+
+def wrap_asgi_application(application: ASGIApp) -> ASGIApp:
+    """
+    Wrap a Django (or other) ASGI HTTP app to emit one footprint per request.
+
+    Pass the return value of `get_asgi_application()` or the ``"http"`` branch
+    of a ``ProtocolTypeRouter``. Pair with ``DjangoIntegration(auto_perf=False)``.
+    """
+    return _InsiderAsgiHttpWrapper(application)
+
+
+class _InsiderAsgiHttpWrapper:
+    def __init__(self, app: ASGIApp) -> None:
+        self.app = app
+
+    async def __call__(
+        self,
+        scope: MutableMapping[str, Any],
+        receive: Callable[..., Any],
+        send: Callable[..., Any],
+    ) -> None:
+        if scope.get("type") != "http":
+            await self.app(scope, receive, send)
+            return
+
+        client = _client()
+        if client is None:
+            await self.app(scope, receive, send)
+            return
+
+        trace_id = uuid.uuid4().hex
+        client.scope.set_trace_id(trace_id)
+        client.scope.set_request(
+            build_request_ctx_from_scope(scope, client.send_default_pii)
+        )
+
+        start = time.perf_counter()
+        status_code: Optional[int] = None
+
+        async def send_wrapper(message: Dict[str, Any]) -> None:
+            nonlocal status_code
+            if message.get("type") == "http.response.start":
+                status_code = int(message.get("status", 500))
+            await send(message)
+
+        try:
+            await self.app(scope, receive, send_wrapper)
+        except BaseException as exc:
+            block = exception_payload(
+                exc, in_app_include=client.scope.static.in_app_include
+            )
+            client.scope.set_pending_exception(block)
+            raise
+        finally:
+            path = str(scope.get("path") or "/")
+            method = str(scope.get("method") or "GET")
+            emit_http_footprint(
+                path=path,
+                method=method,
+                duration_ms=(time.perf_counter() - start) * 1000.0,
+                status_code=status_code,
+                trace_id=trace_id,
+            )
+            client.scope.clear_request_cycle()

{insider_python-0.1.4 → insider_python-0.1.5}/src/insider/integrations/django/capture.py

@@ -16,6 +16,19 @@ from ...stacktrace import exception_payload
 from .request import build_request_ctx
 
 _CAPTURED_ATTR = "_insider_exception_captured"
+_PENDING_BLOCK_ATTR = "_insider_pending_exception_block"
+
+
+def sync_pending_from_request(request: Any) -> None:
+    """Copy exception buffered on the request (async worker thread) onto scope."""
+    client = _client()
+    if client is None:
+        return
+    if client.scope.current_pending_exception() is not None:
+        return
+    block = getattr(request, _PENDING_BLOCK_ATTR, None)
+    if block is not None:
+        client.scope.set_pending_exception(block)
 
 
 @safe
@@ -42,4 +55,5 @@ def capture_request_exception(request: Any, exception: BaseException) -> None:
     block = exception_payload(
         exception, in_app_include=client.scope.static.in_app_include
     )
+    setattr(request, _PENDING_BLOCK_ATTR, block)
     client.scope.set_pending_exception(block)

insider_python-0.1.5/src/insider/integrations/django/handler.py

@@ -0,0 +1,133 @@
+"""
+Patch `BaseHandler.get_response` / `get_response_async` for request context
+and auto perf timing.
+
+We patch the handler (not middleware) because:
+
+  - Customers already init in `wsgi.py` / `asgi.py` without touching INSTALLED_APPS.
+  - The patch wraps the entire handler, including middleware inside Django's
+    request cycle.
+  - Perf timing in `finally` runs once per request whether the view returns
+    200 or raises (converted to 500 by Django).
+
+Django 4.1+ ASGI uses `get_response_async` for the async request path
+(Daphne, `AsyncClient`). Both sync and async entrypoints are patched.
+"""
+
+from __future__ import annotations
+
+import time
+import uuid
+from typing import Any, Callable
+
+from ...client import _client
+from ...safety import debug, safe
+from .perf import emit_request_envelope
+from .capture import sync_pending_from_request
+
+_patched = False
+_auto_perf = True
+
+
+def _finalize_request_cycle(
+    request: Any,
+    *,
+    start: float,
+    response: Any,
+    status_code: int | None,
+    trace_id: str,
+) -> None:
+    client = _client()
+    if client is None:
+        return
+    duration_ms = (time.perf_counter() - start) * 1000.0
+    if status_code is None and response is not None:
+        status_code = getattr(response, "status_code", None)
+    sync_pending_from_request(request)
+    if _auto_perf:
+        emit_request_envelope(
+            request,
+            duration_ms=duration_ms,
+            status_code=status_code,
+            trace_id=trace_id,
+        )
+        client.scope.clear_request_cycle()
+    # When auto_perf=False (e.g. wrap_asgi_application), leave scope intact
+    # for the outer ASGI wrapper to emit one combined footprint.
+
+
+def install(*, auto_perf: bool = True) -> None:
+    global _patched, _auto_perf
+    _auto_perf = auto_perf
+    if _patched:
+        return
+    try:
+        from django.core.handlers.base import BaseHandler
+    except ImportError:
+        debug("django BaseHandler unavailable; skipping get_response patch")
+        return
+
+    old_get_response = BaseHandler.get_response
+    old_get_response_async = BaseHandler.get_response_async
+
+    @safe
+    def patched_get_response(self: Any, request: Any) -> Any:
+        client = _client()
+        if client is None:
+            return old_get_response(self, request)
+
+        trace_id = uuid.uuid4().hex
+        client.scope.set_trace_id(trace_id)
+        from .request import build_request_ctx
+
+        ctx = build_request_ctx(request, client.send_default_pii)
+        client.scope.set_request(ctx)
+
+        start = time.perf_counter()
+        response = None
+        status_code: int | None = None
+        try:
+            response = old_get_response(self, request)
+            status_code = getattr(response, "status_code", None)
+            return response
+        finally:
+            _finalize_request_cycle(
+                request,
+                start=start,
+                response=response,
+                status_code=status_code,
+                trace_id=trace_id,
+            )
+
+    @safe
+    async def patched_get_response_async(self: Any, request: Any) -> Any:
+        client = _client()
+        if client is None:
+            return await old_get_response_async(self, request)
+
+        trace_id = uuid.uuid4().hex
+        client.scope.set_trace_id(trace_id)
+        from .request import build_request_ctx
+
+        ctx = build_request_ctx(request, client.send_default_pii)
+        client.scope.set_request(ctx)
+
+        start = time.perf_counter()
+        response = None
+        status_code: int | None = None
+        try:
+            response = await old_get_response_async(self, request)
+            status_code = getattr(response, "status_code", None)
+            return response
+        finally:
+            _finalize_request_cycle(
+                request,
+                start=start,
+                response=response,
+                status_code=status_code,
+                trace_id=trace_id,
+            )
+
+    BaseHandler.get_response = patched_get_response  # type: ignore[method-assign]
+    BaseHandler.get_response_async = patched_get_response_async  # type: ignore[method-assign]
+    _patched = True

{insider_python-0.1.4 → insider_python-0.1.5}/src/insider/integrations/django/perf.py

@@ -14,9 +14,10 @@ from ...safety import safe
 
 
 @safe
-def emit_request_envelope(
-    request: Any,
+def emit_http_footprint(
     *,
+    path: str,
+    method: Optional[str],
     duration_ms: float,
     status_code: Optional[int],
     trace_id: Optional[str],
@@ -26,9 +27,7 @@ def emit_request_envelope(
     if client is None:
         return
 
-    method = getattr(request, "method", None)
-    op = getattr(request, "path", None) or "unknown"
-
+    op = path or "unknown"
     client.capture_request(
         duration_ms=duration_ms,
         op=op,
@@ -36,3 +35,21 @@ def emit_request_envelope(
         method=method,
         trace_id=trace_id,
     )
+
+
+@safe
+def emit_request_envelope(
+    request: Any,
+    *,
+    duration_ms: float,
+    status_code: Optional[int],
+    trace_id: Optional[str],
+) -> None:
+    """Build and ship a single `kind=request` beacon from a Django request."""
+    emit_http_footprint(
+        path=getattr(request, "path", None) or "unknown",
+        method=getattr(request, "method", None),
+        duration_ms=duration_ms,
+        status_code=status_code,
+        trace_id=trace_id,
+    )

{insider_python-0.1.4 → insider_python-0.1.5}/src/insider/integrations/django/request.py

@@ -39,6 +39,47 @@ def attach_drf_request_backref(django_request: Any, drf_request: Any) -> None:
         debug(f"drf request backref failed: {exc}")
 
 
+def build_request_ctx_from_scope(
+    scope: Any,
+    send_default_pii: bool,
+) -> Dict[str, Any]:
+    """Build request context from a raw ASGI HTTP scope."""
+    try:
+        headers: Dict[str, str] = {}
+        for key, value in scope.get("headers") or []:
+            try:
+                name = key.decode("latin-1").lower().replace("_", "-")
+                val = value.decode("latin-1")
+            except Exception:
+                continue
+            if name not in _SAFE_HEADERS and len(val) > 4096:
+                continue
+            headers[name] = val
+
+        query_raw = scope.get("query_string") or b""
+        query = (
+            query_raw.decode("latin-1", errors="replace") if query_raw else None
+        )
+        path = scope.get("path")
+        method = scope.get("method")
+        client = scope.get("client")
+        ip = client[0] if client else None
+
+        ctx: Dict[str, Any] = {
+            "method": method,
+            "path": path,
+            "query_string": query,
+            "headers": headers,
+            "ip": ip,
+        }
+        if send_default_pii and ip:
+            ctx["ip_address"] = ip
+        return ctx
+    except Exception as exc:
+        debug(f"asgi scope ctx build failed: {exc}")
+        return {}
+
+
 def build_request_ctx(request: Any, send_default_pii: bool) -> Dict[str, Any]:
     try:
         request = _resolve_drf_request(request)