errorgap 0.3.0__tar.gz → 0.4.0__tar.gz

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

@@ -1,5 +1,14 @@
 # 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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: errorgap
-Version: 0.3.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
@@ -181,6 +181,32 @@ 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 |
@@ -196,6 +222,8 @@ Record spans from an endpoint with `errorgap.fastapi.spans(request).database(sql
 | `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.3.0 → errorgap-0.4.0}/README.md

@@ -145,6 +145,32 @@ 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 |
@@ -160,6 +186,8 @@ Record spans from an endpoint with `errorgap.fastapi.spans(request).database(sql
 | `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.3.0 → errorgap-0.4.0}/pyproject.toml

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

{errorgap-0.3.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.3.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.3.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.3.0 → errorgap-0.4.0}/src/errorgap/django.py

@@ -24,6 +24,7 @@ class ErrorgapMiddleware:
 
     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 {}
@@ -136,3 +137,42 @@ def _params(request: Any) -> Dict[str, Any]:
     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/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.3.0 → errorgap-0.4.0}/tests/test_django.py

@@ -109,3 +109,29 @@ def test_requests_are_transactions_linked_to_their_errors(ingestor, reset_errorg
     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_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.3.0/src/errorgap/version.py

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