errorgap 0.2.0__tar.gz → 0.4.0__tar.gz

{errorgap-0.2.0 → errorgap-0.4.0}/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 0.4.0 — 2026-10-06
+
+- Sign-ins: `init(auth_events=True)` reports sign-ins to errorgap's
+  Security › Logins. Django's `user_logged_in` / `user_login_failed` signals
+  are reported automatically with the middleware installed;
+  `errorgap.sign_in(outcome, user=, request=)` covers Flask, FastAPI and
+  other outcomes (`password_reset`, `mfa_failure`, `locked`). `app_name`
+  (or `ERRORGAP_APP_NAME`) names the app. Passwords and tokens are never sent.
+
+## 0.3.0 — 2026-10-04
+
+- Django and FastAPI/Starlette middleware now time each request as an APM
+  transaction (with `apm_enabled`), grouped by URL pattern / route path, with
+  errors linked to their request and the browser's `x-errorgap-trace` header
+  recorded. `errorgap.django.spans(request)` / `errorgap.fastapi.spans(request)`
+  record spans.
+
 ## 0.2.0 — 2026-10-03
 
 - APM: `track_transaction` / `track_job` context managers, `notify_transaction`,

{errorgap-0.2.0 → errorgap-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: errorgap
-Version: 0.2.0
+Version: 0.4.0
 Summary: Python notifier for Errorgap error tracking.
 Project-URL: Homepage, https://github.com/errorgaphq/errorgap-python
 Project-URL: Source, https://github.com/errorgaphq/errorgap-python
@@ -97,6 +97,11 @@ MIDDLEWARE = [
 ]
 ```
 
+With `apm_enabled=True` each request is also an APM transaction grouped by
+its URL pattern (`/orders/<int:order_id>`); errors raised during it carry its
+transaction id, and the browser SDK's `x-errorgap-trace` header is recorded.
+Record spans from a view with `errorgap.django.spans(request).database(sql, ms)`.
+
 ## Flask
 
 ```python
@@ -155,8 +160,8 @@ concurrent threads and asyncio tasks never share one;
 ## Browser trace links
 
 When the errorgap browser SDK (`@errorgap/browser` 0.3+) is on the page, its
-API calls send an `x-errorgap-trace` header. The WSGI middleware (and so
-`init_app`) records it, and `track_transaction(..., trace_id=header)` accepts
+API calls send an `x-errorgap-trace` header. The WSGI, Django and FastAPI
+middleware (and so Flask's `init_app`) record it, and `track_transaction(..., trace_id=header)` accepts
 it, so errorgap's browser Performance view links each call to the server
 request that answered it. Malformed values are ignored.
 
@@ -170,6 +175,38 @@ app = FastAPI()
 app.add_middleware(ErrorgapMiddleware)
 ```
 
+With `apm_enabled=True` each request is also an APM transaction grouped by
+its route path (`/orders/{order_id}`); errors raised during it carry its
+transaction id, and the browser SDK's `x-errorgap-trace` header is recorded.
+Record spans from an endpoint with `errorgap.fastapi.spans(request).database(sql, ms)`
+(take `request: Request` as a parameter).
+
+## Sign-ins
+
+Report sign-ins to your app; errorgap shows them beside SSH logins in
+Security › Logins and flags a new IP, country or hour for a user. Off until
+you opt in, since events carry user names and IPs:
+
+```python
+errorgap.init(project_slug="ox-coffee", auth_events=True, app_name="oxcoffee-web")
+```
+
+**Django** needs nothing else: with `ErrorgapMiddleware` installed, Django's
+`user_logged_in` and `user_login_failed` signals are reported (the user's
+`get_username()`; Django masks the password before the signal). Elsewhere,
+or for other outcomes:
+
+```python
+errorgap.sign_in("success" if ok else "failure", user=email, request=request)
+errorgap.sign_in("mfa_failure", user=email, request=request)
+```
+
+Outcomes: `success`, `failure`, `password_reset`, `mfa_failure`, `locked`.
+A Django, Flask or Starlette `request` supplies the IP, user agent and path
+(without the query string); behind a proxy, pass `ip=` yourself. Never pass
+passwords or tokens; errorgap can also store user names hashed
+(Security › Logins › Web apps › Privacy).
+
 ## Configuration reference
 
 | Argument | Default | Notes |
@@ -185,6 +222,8 @@ app.add_middleware(ErrorgapMiddleware)
 | `filter_keys` | `("password", "token", ...)` | Substring match, case-insensitive |
 | `apm_enabled` | `False` | Send APM transactions |
 | `apm_sample_rate` | `1.0` | Fraction of transactions sent (errors are unaffected) |
+| `auth_events` | `False` | Send sign-ins (`sign_in`, Django login signals) |
+| `app_name` | `ERRORGAP_APP_NAME` or the project slug | The app's name in Security › Logins |
 | `capture_globals` | `True` | Install `sys.excepthook` |
 
 ## Graceful shutdown

{errorgap-0.2.0 → errorgap-0.4.0}/README.md

@@ -61,6 +61,11 @@ MIDDLEWARE = [
 ]
 ```
 
+With `apm_enabled=True` each request is also an APM transaction grouped by
+its URL pattern (`/orders/<int:order_id>`); errors raised during it carry its
+transaction id, and the browser SDK's `x-errorgap-trace` header is recorded.
+Record spans from a view with `errorgap.django.spans(request).database(sql, ms)`.
+
 ## Flask
 
 ```python
@@ -119,8 +124,8 @@ concurrent threads and asyncio tasks never share one;
 ## Browser trace links
 
 When the errorgap browser SDK (`@errorgap/browser` 0.3+) is on the page, its
-API calls send an `x-errorgap-trace` header. The WSGI middleware (and so
-`init_app`) records it, and `track_transaction(..., trace_id=header)` accepts
+API calls send an `x-errorgap-trace` header. The WSGI, Django and FastAPI
+middleware (and so Flask's `init_app`) record it, and `track_transaction(..., trace_id=header)` accepts
 it, so errorgap's browser Performance view links each call to the server
 request that answered it. Malformed values are ignored.
 
@@ -134,6 +139,38 @@ app = FastAPI()
 app.add_middleware(ErrorgapMiddleware)
 ```
 
+With `apm_enabled=True` each request is also an APM transaction grouped by
+its route path (`/orders/{order_id}`); errors raised during it carry its
+transaction id, and the browser SDK's `x-errorgap-trace` header is recorded.
+Record spans from an endpoint with `errorgap.fastapi.spans(request).database(sql, ms)`
+(take `request: Request` as a parameter).
+
+## Sign-ins
+
+Report sign-ins to your app; errorgap shows them beside SSH logins in
+Security › Logins and flags a new IP, country or hour for a user. Off until
+you opt in, since events carry user names and IPs:
+
+```python
+errorgap.init(project_slug="ox-coffee", auth_events=True, app_name="oxcoffee-web")
+```
+
+**Django** needs nothing else: with `ErrorgapMiddleware` installed, Django's
+`user_logged_in` and `user_login_failed` signals are reported (the user's
+`get_username()`; Django masks the password before the signal). Elsewhere,
+or for other outcomes:
+
+```python
+errorgap.sign_in("success" if ok else "failure", user=email, request=request)
+errorgap.sign_in("mfa_failure", user=email, request=request)
+```
+
+Outcomes: `success`, `failure`, `password_reset`, `mfa_failure`, `locked`.
+A Django, Flask or Starlette `request` supplies the IP, user agent and path
+(without the query string); behind a proxy, pass `ip=` yourself. Never pass
+passwords or tokens; errorgap can also store user names hashed
+(Security › Logins › Web apps › Privacy).
+
 ## Configuration reference
 
 | Argument | Default | Notes |
@@ -149,6 +186,8 @@ app.add_middleware(ErrorgapMiddleware)
 | `filter_keys` | `("password", "token", ...)` | Substring match, case-insensitive |
 | `apm_enabled` | `False` | Send APM transactions |
 | `apm_sample_rate` | `1.0` | Fraction of transactions sent (errors are unaffected) |
+| `auth_events` | `False` | Send sign-ins (`sign_in`, Django login signals) |
+| `app_name` | `ERRORGAP_APP_NAME` or the project slug | The app's name in Security › Logins |
 | `capture_globals` | `True` | Install `sys.excepthook` |
 
 ## Graceful shutdown

{errorgap-0.2.0 → errorgap-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "errorgap"
-version = "0.2.0"
+version = "0.4.0"
 description = "Python notifier for Errorgap error tracking."
 readme = "README.md"
 license = { text = "MIT" }

{errorgap-0.2.0 → errorgap-0.4.0}/src/errorgap/__init__.py

@@ -18,6 +18,7 @@ __all__ = [
     "notify_transaction",
     "track_transaction",
     "track_job",
+    "sign_in",
     "current_transaction_id",
     "transaction_scope",
     "browser_trace_id",
@@ -53,6 +54,8 @@ def init(
     logger: Optional[Any] = None,
     apm_enabled: Optional[bool] = None,
     apm_sample_rate: Optional[float] = None,
+    auth_events: Optional[bool] = None,
+    app_name: Optional[str] = None,
     capture_globals: bool = True,
 ) -> None:
     """Configure the SDK and install global error hooks.
@@ -86,6 +89,10 @@ def init(
         overrides["apm_enabled"] = apm_enabled
     if apm_sample_rate is not None:
         overrides["apm_sample_rate"] = apm_sample_rate
+    if auth_events is not None:
+        overrides["auth_events"] = auth_events
+    if app_name is not None:
+        overrides["app_name"] = app_name
 
     _configuration = Configuration(**overrides)
     _client.configure(_configuration)
@@ -114,6 +121,27 @@ def notify(
     )
 
 
+def sign_in(
+    outcome: str,
+    user: Any = None,
+    request: Any = None,
+    ip: Optional[str] = None,
+    user_agent: Optional[str] = None,
+    path: Optional[str] = None,
+    method: Optional[str] = None,
+    sync: bool = False,
+) -> DeliveryResult:
+    """Report a sign-in to this app: ``"success"``, ``"failure"``,
+    ``"password_reset"``, ``"mfa_failure"`` or ``"locked"``. Pass the
+    Django, Flask or Starlette ``request`` for its IP, user agent and path.
+    Needs ``init(auth_events=True)``; Django's login signals report
+    automatically with the middleware installed."""
+    return _client.sign_in(
+        outcome, sync=sync, user=user, request=request, ip=ip,
+        user_agent=user_agent, path=path, method=method,
+    )
+
+
 def notify_transaction(transaction: Transaction, sync: bool = False) -> DeliveryResult:
     """Deliver a pre-measured APM transaction."""
     return _client.notify_transaction(transaction, sync=sync)

{errorgap-0.2.0 → errorgap-0.4.0}/src/errorgap/client.py

@@ -13,6 +13,7 @@ from urllib import request as urlrequest
 from .apm import Transaction
 from .configuration import Configuration
 from .notice import build_notice
+from .sign_ins import build_sign_in, sign_in_payload
 from .transaction_context import current_transaction_id
 from .version import VERSION
 
@@ -98,6 +99,28 @@ class Client:
         self._queue.put(("transactions", payload))
         return DeliveryResult(queued=True, status=202)
 
+    def sign_in(self, outcome: str, sync: bool = False, **fields: Any) -> DeliveryResult:
+        """Report a sign-in to this app (Security › Logins). Dropped unless
+        ``auth_events`` is on, or when the outcome is unknown."""
+        try:
+            self._configuration.validate()
+            if not self._configuration.auth_events:
+                return DeliveryResult(status=204)
+            event = build_sign_in(outcome, **fields)
+            if event is None:
+                raise ValueError(f"unknown sign-in outcome {outcome!r}")
+            payload = sign_in_payload(event, self._configuration)
+        except Exception as caught:  # noqa: BLE001 — SDK must not raise
+            self._log(caught)
+            return DeliveryResult(error=caught)
+
+        if sync or not self._configuration.async_:
+            return self._post("logins/web", payload)
+
+        self._ensure_worker()
+        self._queue.put(("logins/web", payload))
+        return DeliveryResult(queued=True, status=202)
+
     def deliver(self, notice: Dict[str, Any]) -> DeliveryResult:
         return self._post("notices", notice)
 

{errorgap-0.2.0 → errorgap-0.4.0}/src/errorgap/configuration.py

@@ -39,6 +39,11 @@ class Configuration:
     filter_keys: tuple = DEFAULT_FILTER_KEYS
     apm_enabled: bool = False
     apm_sample_rate: float = 1.0
+    # Sign-ins to this app (Security › Logins). Off until you opt in: they
+    # carry user names and IPs.
+    auth_events: bool = False
+    # The app's name in Security › Logins; defaults to the project slug.
+    app_name: Optional[str] = field(default_factory=lambda: os.environ.get("ERRORGAP_APP_NAME"))
 
     def validate(self) -> None:
         if not self.project_slug or not str(self.project_slug).strip():

errorgap-0.4.0/src/errorgap/django.py

@@ -0,0 +1,178 @@
+from __future__ import annotations
+
+import time
+from datetime import datetime, timezone
+from typing import Any, Callable, Dict, Optional
+
+from . import notify
+from .apm import SpanCollector, Transaction, browser_trace_id
+from .transaction_context import new_transaction_id, transaction_scope
+
+_TRANSACTION_ATTR = "errorgap_transaction"
+
+
+class ErrorgapMiddleware:
+    """Django middleware that reports unhandled exceptions to Errorgap and
+    times each request as an APM transaction (sent with ``apm_enabled``),
+    grouped by its URL pattern. Errors raised during the request carry its
+    transaction id, and the browser SDK's ``x-errorgap-trace`` header links
+    the browser's view of the call to it.
+
+    Add ``"errorgap.django.ErrorgapMiddleware"`` to ``MIDDLEWARE``. Place it
+    early so it sees exceptions raised by inner middleware too.
+    """
+
+    def __init__(self, get_response: Callable[..., Any]):
+        self.get_response = get_response
+        install_auth_signals()
+
+    def __call__(self, request: Any) -> Any:
+        meta = getattr(request, "META", {}) or {}
+        txn = Transaction(
+            kind="web",
+            id=new_transaction_id(),
+            trace_id=browser_trace_id(meta.get("HTTP_X_ERRORGAP_TRACE")),
+            method=getattr(request, "method", None),
+            path_raw=getattr(request, "path", None) or "/",
+            occurred_at=datetime.now(timezone.utc).isoformat(timespec="milliseconds").replace("+00:00", "Z"),
+        )
+        try:
+            setattr(request, _TRANSACTION_ATTR, txn)
+        except Exception:  # noqa: BLE001
+            pass
+        start = time.perf_counter()
+        response = None
+        try:
+            with transaction_scope(txn.id or new_transaction_id()):
+                response = self.get_response(request)
+            return response
+        finally:
+            txn.status_code = getattr(response, "status_code", None) or 500
+            txn.duration_ms = (time.perf_counter() - start) * 1000.0
+            txn.path = _route(request) or txn.path_raw
+            _send_transaction(txn)
+
+    def process_exception(self, request: Any, exception: BaseException) -> Optional[Any]:
+        notify(
+            exception,
+            sync=True,
+            context=_context(request),
+            environment=_environment(request),
+            session=_session(request),
+            params=_params(request),
+        )
+        # Returning None lets Django continue its exception handling chain.
+        return None
+
+
+def spans(request: Any) -> Optional[SpanCollector]:
+    """The span collector for ``request``'s transaction, for recording DB and
+    outbound HTTP spans from views."""
+    txn = getattr(request, _TRANSACTION_ATTR, None)
+    return txn.spans if txn is not None else None
+
+
+def _route(request: Any) -> Optional[str]:
+    """The matched URL pattern (``/orders/<int:id>``), when one matched."""
+    match = getattr(request, "resolver_match", None)
+    route = getattr(match, "route", None) if match is not None else None
+    if not route:
+        return None
+    return route if route.startswith("/") else "/" + route
+
+
+def _send_transaction(txn: Transaction) -> None:
+    import errorgap
+
+    errorgap.notify_transaction(txn)
+
+
+def _context(request: Any) -> Dict[str, Any]:
+    try:
+        resolver = getattr(request, "resolver_match", None)
+        view_name = resolver.view_name if resolver else None
+    except Exception:  # noqa: BLE001
+        view_name = None
+    try:
+        url = request.build_absolute_uri()
+    except Exception:  # noqa: BLE001
+        url = getattr(request, "path", None)
+    return {
+        "url": url,
+        "component": view_name or getattr(request, "path", None),
+        "action": getattr(request, "method", None),
+    }
+
+
+def _environment(request: Any) -> Dict[str, Any]:
+    meta = getattr(request, "META", {}) or {}
+    return {
+        "method": getattr(request, "method", None),
+        "path": getattr(request, "path", None),
+        "query_string": meta.get("QUERY_STRING"),
+        "user_agent": meta.get("HTTP_USER_AGENT"),
+        "remote_addr": meta.get("REMOTE_ADDR"),
+    }
+
+
+def _session(request: Any) -> Dict[str, Any]:
+    try:
+        session = getattr(request, "session", None)
+        if session is None:
+            return {}
+        return dict(session.items())
+    except Exception:  # noqa: BLE001
+        return {}
+
+
+def _params(request: Any) -> Dict[str, Any]:
+    out: Dict[str, Any] = {}
+    try:
+        for key, value in (getattr(request, "GET", {}) or {}).items():
+            out[key] = value
+        post = getattr(request, "POST", None)
+        if post:
+            for key, value in post.items():
+                out[key] = value
+    except Exception:  # noqa: BLE001
+        return out
+    return out
+
+
+def _on_logged_in(sender: Any, request: Any = None, user: Any = None, **_kwargs: Any) -> None:
+    from . import configuration, sign_in
+
+    if request is None or not configuration().auth_events:
+        return
+    name = user.get_username() if hasattr(user, "get_username") else getattr(user, "pk", None)
+    sign_in("success", user=name, request=request)
+
+
+def _on_login_failed(sender: Any, credentials: Any = None, request: Any = None, **_kwargs: Any) -> None:
+    from . import configuration, sign_in
+
+    # No request: a failed check outside a web request (a shell, a test).
+    if request is None or not configuration().auth_events:
+        return
+    creds = credentials or {}
+    try:
+        from django.contrib.auth import get_user_model
+
+        field = get_user_model().USERNAME_FIELD
+    except Exception:  # noqa: BLE001 — auth app not installed
+        field = "username"
+    # Django masks the password in `credentials`; only the name is read.
+    name = next((creds[k] for k in (field, "username", "email") if isinstance(creds.get(k), str)), None)
+    sign_in("failure", user=name, request=request)
+
+
+def install_auth_signals() -> None:
+    """Report Django's login signals (``user_logged_in``,
+    ``user_login_failed``) as sign-ins. The middleware calls this; it checks
+    ``auth_events`` per event, so ``init`` may run before or after."""
+    try:
+        from django.contrib.auth.signals import user_logged_in, user_login_failed
+    except Exception:  # noqa: BLE001 — django.contrib.auth not available
+        return
+    user_logged_in.connect(_on_logged_in, dispatch_uid="errorgap.sign_in.success")
+    user_login_failed.connect(_on_login_failed, dispatch_uid="errorgap.sign_in.failure")

errorgap-0.4.0/src/errorgap/fastapi.py

@@ -0,0 +1,120 @@
+from __future__ import annotations
+
+import time
+from datetime import datetime, timezone
+from typing import Any, Callable, Dict, Optional
+
+from . import notify
+from .apm import SpanCollector, Transaction, browser_trace_id
+from .transaction_context import new_transaction_id, transaction_scope
+
+#: ASGI scope key holding the request's :class:`~errorgap.apm.Transaction`.
+TRANSACTION_KEY = "errorgap.transaction"
+
+
+class ErrorgapMiddleware:
+    """Pure ASGI middleware that reports unhandled exceptions to Errorgap and
+    times each request as an APM transaction (sent with ``apm_enabled``),
+    grouped by its route path (``/orders/{order_id}``). Errors raised during
+    the request carry its transaction id, and the browser SDK's
+    ``x-errorgap-trace`` header links the browser's view of the call to it.
+
+    Usage::
+
+        from fastapi import FastAPI
+        from errorgap.fastapi import ErrorgapMiddleware
+
+        app = FastAPI()
+        app.add_middleware(ErrorgapMiddleware)
+    """
+
+    def __init__(self, app: Callable[..., Any]) -> None:
+        self.app = app
+
+    async def __call__(self, scope: Dict[str, Any], receive: Callable, send: Callable) -> None:
+        if scope.get("type") != "http":
+            await self.app(scope, receive, send)
+            return
+
+        headers = dict(scope.get("headers", []))
+        txn = Transaction(
+            kind="web",
+            id=new_transaction_id(),
+            trace_id=browser_trace_id(headers.get(b"x-errorgap-trace")),
+            method=scope.get("method"),
+            path_raw=scope.get("path") or "/",
+            occurred_at=datetime.now(timezone.utc).isoformat(timespec="milliseconds").replace("+00:00", "Z"),
+        )
+        scope[TRANSACTION_KEY] = txn
+        start = time.perf_counter()
+
+        async def _send(message: Dict[str, Any]) -> None:
+            if message.get("type") == "http.response.start":
+                txn.status_code = message.get("status")
+            await send(message)
+
+        try:
+            with transaction_scope(txn.id or new_transaction_id()):
+                try:
+                    await self.app(scope, receive, _send)
+                except Exception as exc:
+                    txn.status_code = 500
+                    notify(
+                        exc,
+                        sync=True,
+                        context=_context(scope),
+                        environment=_environment(scope),
+                    )
+                    raise
+        finally:
+            import errorgap
+
+            txn.duration_ms = (time.perf_counter() - start) * 1000.0
+            txn.path = _route(scope) or txn.path_raw
+            if txn.status_code is None:
+                txn.status_code = 500
+            errorgap.notify_transaction(txn)
+
+
+def spans(request: Any) -> Optional[SpanCollector]:
+    """The span collector for the request's transaction (a Starlette/FastAPI
+    ``Request``), for recording DB and outbound HTTP spans from endpoints."""
+    txn = getattr(request, "scope", {}).get(TRANSACTION_KEY)
+    return txn.spans if txn is not None else None
+
+
+def _route(scope: Dict[str, Any]) -> Optional[str]:
+    """The matched route's path template, which FastAPI's router records."""
+    route = scope.get("route")
+    path = getattr(route, "path", None)
+    return path if isinstance(path, str) and path else None
+
+
+def _context(scope: Dict[str, Any]) -> Dict[str, Any]:
+    return {
+        "url": _build_url(scope),
+        "component": scope.get("path"),
+        "action": scope.get("method"),
+    }
+
+
+def _environment(scope: Dict[str, Any]) -> Dict[str, Any]:
+    headers = {k.decode("latin1"): v.decode("latin1") for k, v in scope.get("headers", [])}
+    client = scope.get("client") or (None, None)
+    return {
+        "method": scope.get("method"),
+        "path": scope.get("path"),
+        "query_string": scope.get("query_string", b"").decode("utf-8", errors="replace"),
+        "user_agent": headers.get("user-agent"),
+        "remote_addr": client[0],
+    }
+
+
+def _build_url(scope: Dict[str, Any]) -> str:
+    scheme = scope.get("scheme", "http")
+    headers = dict(scope.get("headers", []))
+    host = headers.get(b"host", b"").decode("latin1") or "localhost"
+    path = scope.get("path", "/")
+    query = scope.get("query_string", b"").decode("utf-8", errors="replace")
+    suffix = f"?{query}" if query else ""
+    return f"{scheme}://{host}{path}{suffix}"

errorgap-0.4.0/src/errorgap/sign_ins.py

@@ -0,0 +1,85 @@
+"""Sign-ins to this app, shown beside SSH logins in errorgap's
+Security › Logins. Only who, from where and the result are sent: never
+passwords, tokens or session ids."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Any, Dict, Optional
+
+from .configuration import Configuration
+from .version import VERSION
+
+OUTCOMES = ("success", "failure", "password_reset", "mfa_failure", "locked")
+
+
+def _request_fields(request: Any) -> Dict[str, Optional[str]]:
+    """IP, user agent and path from a Django, Flask/Werkzeug or Starlette
+    request. Paths never include the query string."""
+    meta = getattr(request, "META", None)
+    if isinstance(meta, dict):  # Django
+        return {
+            "ip": meta.get("REMOTE_ADDR"),
+            "user_agent": meta.get("HTTP_USER_AGENT"),
+            "path": f"{request.method} {request.path}",
+        }
+    client = getattr(request, "client", None)
+    url = getattr(request, "url", None)
+    if client is not None and hasattr(url, "path"):  # Starlette / FastAPI
+        return {
+            "ip": getattr(client, "host", None),
+            "user_agent": request.headers.get("user-agent"),
+            "path": f"{request.method} {url.path}",
+        }
+    headers = getattr(request, "headers", None) or {}
+    return {  # Flask / Werkzeug
+        "ip": getattr(request, "remote_addr", None),
+        "user_agent": headers.get("User-Agent") if hasattr(headers, "get") else None,
+        "path": f"{getattr(request, 'method', '')} {getattr(request, 'path', '')}".strip() or None,
+    }
+
+
+def build_sign_in(
+    outcome: str,
+    user: Any = None,
+    request: Any = None,
+    ip: Optional[str] = None,
+    user_agent: Optional[str] = None,
+    path: Optional[str] = None,
+    method: Optional[str] = None,
+    occurred_at: Optional[datetime] = None,
+) -> Optional[Dict[str, Any]]:
+    """The event to send, or ``None`` for an unknown outcome."""
+    if outcome not in OUTCOMES:
+        return None
+    if request is not None:
+        found = _request_fields(request)
+        ip = ip or found["ip"]
+        user_agent = user_agent or found["user_agent"]
+        path = path or found["path"]
+    at = (occurred_at or datetime.now(timezone.utc)).astimezone(timezone.utc)
+    event: Dict[str, Any] = {
+        "occurred_at": at.isoformat(timespec="milliseconds").replace("+00:00", "Z"),
+        "outcome": outcome,
+    }
+    name = "" if user is None else str(user).strip()
+    if name:
+        event["user"] = name
+    if ip:
+        event["ip"] = str(ip)
+    if user_agent:
+        event["user_agent"] = str(user_agent)[:512]
+    if path:
+        event["path"] = str(path)[:200]
+    if method:
+        event["method"] = str(method)
+    return event
+
+
+def sign_in_payload(event: Dict[str, Any], configuration: Configuration) -> Dict[str, Any]:
+    return {
+        "app": configuration.app_name or configuration.project_slug,
+        "environment": configuration.environment,
+        "sdk": f"errorgap-python {VERSION}",
+        "events": [event],
+    }

errorgap-0.4.0/src/errorgap/version.py

@@ -0,0 +1 @@
+VERSION = "0.4.0"

errorgap-0.4.0/tests/test_django.py

@@ -0,0 +1,137 @@
+from __future__ import annotations
+
+import pytest
+
+django = pytest.importorskip("django")
+
+from django.conf import settings
+from django.http import HttpResponse
+from django.test import RequestFactory
+from django.urls import path
+
+import errorgap
+from errorgap.django import ErrorgapMiddleware
+
+
+@pytest.fixture(scope="module", autouse=True)
+def _django_setup():
+    if not settings.configured:
+        settings.configure(
+            DEBUG=False,
+            ALLOWED_HOSTS=["*"],
+            ROOT_URLCONF=__name__,
+            DATABASES={},
+            INSTALLED_APPS=[],
+            MIDDLEWARE=[],
+            SECRET_KEY="test",
+            DEFAULT_AUTO_FIELD="django.db.models.BigAutoField",
+        )
+        import django as _django
+
+        _django.setup()
+
+
+def _boom(_request):
+    raise RuntimeError("django-boom")
+
+
+urlpatterns = [path("boom", _boom)]
+
+
+def test_middleware_reports_exception(ingestor, reset_errorgap):
+    errorgap.init(
+        endpoint=ingestor.endpoint,
+        project_slug="demo",
+        api_key="flk_test",
+        async_=False,
+        capture_globals=False,
+    )
+
+    factory = RequestFactory()
+    request = factory.get("/boom?x=1")
+
+    middleware = ErrorgapMiddleware(get_response=lambda req: HttpResponse(""))
+
+    try:
+        _boom(request)
+    except RuntimeError as exc:
+        middleware.process_exception(request, exc)
+
+    errorgap.flush(timeout=5)
+    assert len(ingestor.requests) == 1
+    body = ingestor.requests[0].body
+    assert body["errors"][0]["type"] == "RuntimeError"
+    assert body["errors"][0]["message"] == "django-boom"
+    assert body["context"]["action"] == "GET"
+
+
+def _order(request, order_id):
+    from errorgap.django import spans
+
+    spans(request).database("SELECT * FROM orders WHERE id = %d" % order_id, 1.0)
+    errorgap.notify(RuntimeError("card declined"))
+    return HttpResponse("ok", status=201)
+
+
+urlpatterns.append(path("orders/<int:order_id>", _order))
+
+
+def test_requests_are_transactions_linked_to_their_errors(ingestor, reset_errorgap):
+    from django.test import Client
+
+    errorgap.init(
+        endpoint=ingestor.endpoint,
+        project_slug="demo",
+        async_=False,
+        capture_globals=False,
+        apm_enabled=True,
+    )
+    settings.MIDDLEWARE = ["errorgap.django.ErrorgapMiddleware"]
+    try:
+        client = Client(raise_request_exception=False)
+        ok = client.get("/orders/7", HTTP_X_ERRORGAP_TRACE="0192F3C4-7A1B-4C2D-9E3F-0123456789AB")
+        boom = client.get("/boom")
+    finally:
+        settings.MIDDLEWARE = []
+    assert ok.status_code == 201
+    assert boom.status_code == 500
+
+    txns = [r.body for r in ingestor.requests if r.path.endswith("/transactions")]
+    notices = [r.body for r in ingestor.requests if r.path.endswith("/notices")]
+    ok_txn = next(t for t in txns if t["path_raw"] == "/orders/7")
+    boom_txn = next(t for t in txns if t["path_raw"] == "/boom")
+    assert ok_txn["path"] == "/orders/<int:order_id>"
+    assert ok_txn["status_code"] == 201
+    assert ok_txn["trace_id"] == "0192f3c4-7a1b-4c2d-9e3f-0123456789ab"
+    assert ok_txn["spans"][0]["sql"] == "SELECT * FROM orders WHERE id = ?"
+    assert boom_txn["status_code"] == 500
+    assert "trace_id" not in boom_txn
+    by_message = {n["errors"][0]["message"]: n["context"].get("transaction_id") for n in notices}
+    assert by_message["card declined"] == ok_txn["id"]
+    assert by_message["django-boom"] == boom_txn["id"]
+
+
+def test_login_signals_report_sign_ins(ingestor, reset_errorgap):
+    from django.contrib.auth.signals import user_logged_in, user_login_failed
+
+    errorgap.init(endpoint=ingestor.endpoint, project_slug="demo", api_key="k", async_=False,
+                  capture_globals=False, auth_events=True)
+    ErrorgapMiddleware(get_response=lambda req: HttpResponse(""))  # connects the signals
+    request = RequestFactory().post("/accounts/login/", REMOTE_ADDR="198.51.100.71",
+                                    HTTP_USER_AGENT="Firefox/131")
+
+    class User:
+        def get_username(self):
+            return "mara"
+
+    user_logged_in.send(sender=User, request=request, user=User())
+    # Django masks the password before sending the signal.
+    user_login_failed.send(sender=None, request=request,
+                           credentials={"username": "admin", "password": "********************"})
+    # A failed check outside a request is not a sign-in attempt.
+    user_login_failed.send(sender=None, request=None, credentials={"username": "cli"})
+
+    events = [r.body["events"][0] for r in ingestor.requests]
+    assert [(e["outcome"], e["user"]) for e in events] == [("success", "mara"), ("failure", "admin")]
+    assert events[0]["path"] == "POST /accounts/login/"
+    assert events[0]["ip"] == "198.51.100.71"

errorgap-0.4.0/tests/test_fastapi.py

@@ -0,0 +1,82 @@
+from __future__ import annotations
+
+import pytest
+
+fastapi = pytest.importorskip("fastapi")
+
+from fastapi import FastAPI, Request
+from starlette.testclient import TestClient
+
+import errorgap
+from errorgap.fastapi import ErrorgapMiddleware, spans
+
+
+def test_fastapi_middleware_reports_exception(ingestor, reset_errorgap):
+    errorgap.init(
+        endpoint=ingestor.endpoint,
+        project_slug="demo",
+        api_key="flk_test",
+        async_=False,
+        capture_globals=False,
+    )
+
+    app = FastAPI()
+    app.add_middleware(ErrorgapMiddleware)
+
+    @app.get("/boom")
+    def boom():
+        raise RuntimeError("fastapi-boom")
+
+    client = TestClient(app, raise_server_exceptions=False)
+    response = client.get("/boom?x=1")
+    assert response.status_code == 500
+
+    errorgap.flush(timeout=5)
+    assert len(ingestor.requests) == 1
+    body = ingestor.requests[0].body
+    assert body["errors"][0]["type"] == "RuntimeError"
+    assert body["errors"][0]["message"] == "fastapi-boom"
+    assert body["context"]["action"] == "GET"
+
+
+def test_fastapi_requests_are_transactions_linked_to_their_errors(ingestor, reset_errorgap):
+    errorgap.init(
+        endpoint=ingestor.endpoint,
+        project_slug="demo",
+        async_=False,
+        capture_globals=False,
+        apm_enabled=True,
+    )
+
+    app = FastAPI()
+    app.add_middleware(ErrorgapMiddleware)
+
+    @app.get("/orders/{order_id}", status_code=201)
+    async def order(order_id: int, request: Request):
+        spans(request).database("SELECT * FROM orders WHERE id = %d" % order_id, 1.0)
+        errorgap.notify(RuntimeError("card declined"))
+        return {"id": order_id}
+
+    @app.get("/sync/{n}")
+    def sync_boom(n: int):
+        raise RuntimeError("fastapi-boom")
+
+    client = TestClient(app, raise_server_exceptions=False)
+    ok = client.get("/orders/7", headers={"x-errorgap-trace": "0192F3C4-7A1B-4C2D-9E3F-0123456789AB"})
+    boom = client.get("/sync/1")
+    assert ok.status_code == 201
+    assert boom.status_code == 500
+
+    txns = [r.body for r in ingestor.requests if r.path.endswith("/transactions")]
+    notices = [r.body for r in ingestor.requests if r.path.endswith("/notices")]
+    ok_txn = next(t for t in txns if t["path_raw"] == "/orders/7")
+    boom_txn = next(t for t in txns if t["path_raw"] == "/sync/1")
+    assert ok_txn["path"] == "/orders/{order_id}"
+    assert ok_txn["status_code"] == 201
+    assert ok_txn["trace_id"] == "0192f3c4-7a1b-4c2d-9e3f-0123456789ab"
+    assert ok_txn["spans"][0]["sql"] == "SELECT * FROM orders WHERE id = ?"
+    assert boom_txn["path"] == "/sync/{n}"
+    assert boom_txn["status_code"] == 500
+    by_message = {n["errors"][0]["message"]: n["context"].get("transaction_id") for n in notices}
+    assert by_message["card declined"] == ok_txn["id"]
+    assert by_message["fastapi-boom"] == boom_txn["id"]

errorgap-0.4.0/tests/test_sign_ins.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+from types import SimpleNamespace
+
+import errorgap
+from errorgap.sign_ins import build_sign_in
+
+
+def test_flask_like_request_fields():
+    req = SimpleNamespace(
+        remote_addr="198.51.100.71", headers={"User-Agent": "Safari 18"}, method="POST", path="/login"
+    )
+    e = build_sign_in("success", user="mara@oxcoffee.com", request=req)
+    assert e["user"] == "mara@oxcoffee.com"
+    assert (e["ip"], e["user_agent"], e["path"]) == ("198.51.100.71", "Safari 18", "POST /login")
+    assert e["occurred_at"].endswith("Z")
+
+
+def test_starlette_like_request_fields():
+    req = SimpleNamespace(
+        client=SimpleNamespace(host="203.0.113.9"),
+        url=SimpleNamespace(path="/token"),
+        headers={"user-agent": "curl/8"},
+        method="POST",
+    )
+    e = build_sign_in("mfa_failure", request=req)
+    assert (e["ip"], e["path"], "user" in e) == ("203.0.113.9", "POST /token", False)
+
+
+def test_unknown_outcome_is_dropped():
+    assert build_sign_in("teleported") is None
+
+
+def test_sign_in_posts_once_opted_in(ingestor, reset_errorgap):
+    errorgap.init(endpoint=ingestor.endpoint, project_slug="ox-coffee", api_key="k1",
+                  environment="production", async_=False, capture_globals=False)
+    assert errorgap.sign_in("success", user="x").status == 204
+    assert ingestor.requests == []
+
+    errorgap.init(endpoint=ingestor.endpoint, project_slug="ox-coffee", api_key="k1",
+                  environment="production", async_=False, capture_globals=False,
+                  auth_events=True, app_name="oxcoffee-web")
+    errorgap.sign_in("locked", user="admin", ip="203.0.113.9")
+    req = ingestor.requests[0]
+    assert req.path == "/api/projects/ox-coffee/logins/web"
+    assert req.headers["x-errorgap-project-key"] == "k1"
+    assert req.body["app"] == "oxcoffee-web"
+    assert req.body["environment"] == "production"
+    assert req.body["sdk"].startswith("errorgap-python ")
+    assert req.body["events"][0]["outcome"] == "locked"

errorgap-0.2.0/src/errorgap/django.py

@@ -1,83 +0,0 @@
-from __future__ import annotations
-
-from typing import Any, Callable, Dict, Optional
-
-from . import notify
-
-
-class ErrorgapMiddleware:
-    """Django middleware that reports unhandled exceptions to Errorgap.
-
-    Add ``"errorgap.django.ErrorgapMiddleware"`` to ``MIDDLEWARE``. Place it
-    early so it sees exceptions raised by inner middleware too.
-    """
-
-    def __init__(self, get_response: Callable[..., Any]):
-        self.get_response = get_response
-
-    def __call__(self, request: Any) -> Any:
-        return self.get_response(request)
-
-    def process_exception(self, request: Any, exception: BaseException) -> Optional[Any]:
-        notify(
-            exception,
-            sync=True,
-            context=_context(request),
-            environment=_environment(request),
-            session=_session(request),
-            params=_params(request),
-        )
-        # Returning None lets Django continue its exception handling chain.
-        return None
-
-
-def _context(request: Any) -> Dict[str, Any]:
-    try:
-        resolver = getattr(request, "resolver_match", None)
-        view_name = resolver.view_name if resolver else None
-    except Exception:  # noqa: BLE001
-        view_name = None
-    try:
-        url = request.build_absolute_uri()
-    except Exception:  # noqa: BLE001
-        url = getattr(request, "path", None)
-    return {
-        "url": url,
-        "component": view_name or getattr(request, "path", None),
-        "action": getattr(request, "method", None),
-    }
-
-
-def _environment(request: Any) -> Dict[str, Any]:
-    meta = getattr(request, "META", {}) or {}
-    return {
-        "method": getattr(request, "method", None),
-        "path": getattr(request, "path", None),
-        "query_string": meta.get("QUERY_STRING"),
-        "user_agent": meta.get("HTTP_USER_AGENT"),
-        "remote_addr": meta.get("REMOTE_ADDR"),
-    }
-
-
-def _session(request: Any) -> Dict[str, Any]:
-    try:
-        session = getattr(request, "session", None)
-        if session is None:
-            return {}
-        return dict(session.items())
-    except Exception:  # noqa: BLE001
-        return {}
-
-
-def _params(request: Any) -> Dict[str, Any]:
-    out: Dict[str, Any] = {}
-    try:
-        for key, value in (getattr(request, "GET", {}) or {}).items():
-            out[key] = value
-        post = getattr(request, "POST", None)
-        if post:
-            for key, value in post.items():
-                out[key] = value
-    except Exception:  # noqa: BLE001
-        return out
-    return out

errorgap-0.2.0/src/errorgap/fastapi.py

@@ -1,67 +0,0 @@
-from __future__ import annotations
-
-from typing import Any, Callable, Dict
-
-from . import notify
-
-
-class ErrorgapMiddleware:
-    """Pure ASGI middleware that reports unhandled exceptions to Errorgap.
-
-    Usage::
-
-        from fastapi import FastAPI
-        from errorgap.fastapi import ErrorgapMiddleware
-
-        app = FastAPI()
-        app.add_middleware(ErrorgapMiddleware)
-    """
-
-    def __init__(self, app: Callable[..., Any]) -> None:
-        self.app = app
-
-    async def __call__(self, scope: Dict[str, Any], receive: Callable, send: Callable) -> None:
-        if scope.get("type") != "http":
-            await self.app(scope, receive, send)
-            return
-
-        try:
-            await self.app(scope, receive, send)
-        except Exception as exc:
-            notify(
-                exc,
-                sync=True,
-                context=_context(scope),
-                environment=_environment(scope),
-            )
-            raise
-
-
-def _context(scope: Dict[str, Any]) -> Dict[str, Any]:
-    return {
-        "url": _build_url(scope),
-        "component": scope.get("path"),
-        "action": scope.get("method"),
-    }
-
-
-def _environment(scope: Dict[str, Any]) -> Dict[str, Any]:
-    headers = {k.decode("latin1"): v.decode("latin1") for k, v in scope.get("headers", [])}
-    client = scope.get("client") or (None, None)
-    return {
-        "method": scope.get("method"),
-        "path": scope.get("path"),
-        "query_string": scope.get("query_string", b"").decode("utf-8", errors="replace"),
-        "user_agent": headers.get("user-agent"),
-        "remote_addr": client[0],
-    }
-
-
-def _build_url(scope: Dict[str, Any]) -> str:
-    scheme = scope.get("scheme", "http")
-    headers = dict(scope.get("headers", []))
-    host = headers.get(b"host", b"").decode("latin1") or "localhost"
-    path = scope.get("path", "/")
-    query = scope.get("query_string", b"").decode("utf-8", errors="replace")
-    suffix = f"?{query}" if query else ""
-    return f"{scheme}://{host}{path}{suffix}"

errorgap-0.2.0/src/errorgap/version.py

@@ -1 +0,0 @@
-VERSION = "0.2.0"

errorgap-0.2.0/tests/test_django.py

@@ -1,65 +0,0 @@
-from __future__ import annotations
-
-import pytest
-
-django = pytest.importorskip("django")
-
-from django.conf import settings
-from django.http import HttpResponse
-from django.test import RequestFactory
-from django.urls import path
-
-import errorgap
-from errorgap.django import ErrorgapMiddleware
-
-
-@pytest.fixture(scope="module", autouse=True)
-def _django_setup():
-    if not settings.configured:
-        settings.configure(
-            DEBUG=False,
-            ALLOWED_HOSTS=["*"],
-            ROOT_URLCONF=__name__,
-            DATABASES={},
-            INSTALLED_APPS=[],
-            MIDDLEWARE=[],
-            SECRET_KEY="test",
-            DEFAULT_AUTO_FIELD="django.db.models.BigAutoField",
-        )
-        import django as _django
-
-        _django.setup()
-
-
-def _boom(_request):
-    raise RuntimeError("django-boom")
-
-
-urlpatterns = [path("boom", _boom)]
-
-
-def test_middleware_reports_exception(ingestor, reset_errorgap):
-    errorgap.init(
-        endpoint=ingestor.endpoint,
-        project_slug="demo",
-        api_key="flk_test",
-        async_=False,
-        capture_globals=False,
-    )
-
-    factory = RequestFactory()
-    request = factory.get("/boom?x=1")
-
-    middleware = ErrorgapMiddleware(get_response=lambda req: HttpResponse(""))
-
-    try:
-        _boom(request)
-    except RuntimeError as exc:
-        middleware.process_exception(request, exc)
-
-    errorgap.flush(timeout=5)
-    assert len(ingestor.requests) == 1
-    body = ingestor.requests[0].body
-    assert body["errors"][0]["type"] == "RuntimeError"
-    assert body["errors"][0]["message"] == "django-boom"
-    assert body["context"]["action"] == "GET"

errorgap-0.2.0/tests/test_fastapi.py

@@ -1,39 +0,0 @@
-from __future__ import annotations
-
-import pytest
-
-fastapi = pytest.importorskip("fastapi")
-
-from fastapi import FastAPI
-from starlette.testclient import TestClient
-
-import errorgap
-from errorgap.fastapi import ErrorgapMiddleware
-
-
-def test_fastapi_middleware_reports_exception(ingestor, reset_errorgap):
-    errorgap.init(
-        endpoint=ingestor.endpoint,
-        project_slug="demo",
-        api_key="flk_test",
-        async_=False,
-        capture_globals=False,
-    )
-
-    app = FastAPI()
-    app.add_middleware(ErrorgapMiddleware)
-
-    @app.get("/boom")
-    def boom():
-        raise RuntimeError("fastapi-boom")
-
-    client = TestClient(app, raise_server_exceptions=False)
-    response = client.get("/boom?x=1")
-    assert response.status_code == 500
-
-    errorgap.flush(timeout=5)
-    assert len(ingestor.requests) == 1
-    body = ingestor.requests[0].body
-    assert body["errors"][0]["type"] == "RuntimeError"
-    assert body["errors"][0]["message"] == "fastapi-boom"
-    assert body["context"]["action"] == "GET"