analytics-platform 0.2.2__tar.gz → 0.3.1__tar.gz

{analytics_platform-0.2.2 → analytics_platform-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: analytics-platform
-Version: 0.2.2
+Version: 0.3.1
 Summary: Firewall, error monitoring and server analytics for your Python server, run from your analytics dashboard.
 Author: steviec87
 License-Expression: MIT
@@ -158,8 +158,40 @@ except PaymentError as error:
     raise
 ```
 
+Exceptions your code only logs: `errors={"capture_logging": True}` sends an
+exception logged at ERROR or above (`logger.exception(...)`, or
+`exc_info=True`); it is still logged. An exception is sent once however many
+of these see it, and one logged inside a Django, Flask or ASGI request keeps
+that request's route. A batch the collector couldn't take is tried once more
+a few seconds later.
+
+What still can't be sent waits in a file in the temp folder and is sent when
+it can be, after a restart too; each error keeps the time it happened.
+
+Background jobs, as a decorator or a `with` block (sync or async):
+
+```python
+@platform.job("send-receipts")
+def send_receipts(): ...
+```
+
+Their errors carry the job's name as the route, a job that raises is sent
+(status 500) and raised on, and each run is timed (Server speed → Jobs).
+Several services on one site: `Platform(..., server_name="worker")`.
+
+**Several apps on one site** (microservices, a worker, a Node service next to
+this one): install the package in each, with the same `site_id`, `secret` and
+`endpoint`, and a `server_name` of its own. Errors, Server speed, Crawlers and
+Security → Updates then tell the apps apart. Without one, each app is named
+after its machine: two apps on one machine are reported as one, and only the
+last package list sent is kept. A service only your other apps call takes
+`firewall=False, proxy=False, maintenance=False` (its requests all come from
+your own apps, so the rate limit would see one visitor); on a machine shared
+by several apps, keep `resources` on in only one of them.
+
 Options: `server_name`, `root` (traceback paths relative to it),
-`capture_uncaught`, `before_send(event, error)` (change an error, or return
+`capture_uncaught`, `capture_logging`, `spool_dir` (where unsent errors wait;
+`False` for none), `before_send(event, error)` (change an error, or return
 `None` to drop it).
 
 ## Server analytics

{analytics_platform-0.2.2 → analytics_platform-0.3.1}/README.md

@@ -132,8 +132,40 @@ except PaymentError as error:
     raise
 ```
 
+Exceptions your code only logs: `errors={"capture_logging": True}` sends an
+exception logged at ERROR or above (`logger.exception(...)`, or
+`exc_info=True`); it is still logged. An exception is sent once however many
+of these see it, and one logged inside a Django, Flask or ASGI request keeps
+that request's route. A batch the collector couldn't take is tried once more
+a few seconds later.
+
+What still can't be sent waits in a file in the temp folder and is sent when
+it can be, after a restart too; each error keeps the time it happened.
+
+Background jobs, as a decorator or a `with` block (sync or async):
+
+```python
+@platform.job("send-receipts")
+def send_receipts(): ...
+```
+
+Their errors carry the job's name as the route, a job that raises is sent
+(status 500) and raised on, and each run is timed (Server speed → Jobs).
+Several services on one site: `Platform(..., server_name="worker")`.
+
+**Several apps on one site** (microservices, a worker, a Node service next to
+this one): install the package in each, with the same `site_id`, `secret` and
+`endpoint`, and a `server_name` of its own. Errors, Server speed, Crawlers and
+Security → Updates then tell the apps apart. Without one, each app is named
+after its machine: two apps on one machine are reported as one, and only the
+last package list sent is kept. A service only your other apps call takes
+`firewall=False, proxy=False, maintenance=False` (its requests all come from
+your own apps, so the rate limit would see one visitor); on a machine shared
+by several apps, keep `resources` on in only one of them.
+
 Options: `server_name`, `root` (traceback paths relative to it),
-`capture_uncaught`, `before_send(event, error)` (change an error, or return
+`capture_uncaught`, `capture_logging`, `spool_dir` (where unsent errors wait;
+`False` for none), `before_send(event, error)` (change an error, or return
 `None` to drop it).
 
 ## Server analytics

{analytics_platform-0.2.2 → analytics_platform-0.3.1}/analytics_platform/__init__.py

@@ -14,9 +14,11 @@ A module is on with True (or its options as a dict) and off with False.
 No dependencies; Python 3.8+.
 """
 import asyncio
+import functools
 import time
 
 from .core import Core, SESSION_HEADER, VERSION, header, request_target
+from .errors import current_request
 
 __all__ = ["create_platform", "Platform", "PlatformMiddleware", "VERSION"]
 
@@ -78,7 +80,7 @@ class Platform:
     def __init__(self, site_id, secret, endpoint, trust_proxy=None, debug=False, firewall=True, errors=True, analytics=True,
                  performance=True, crawlers=True, forms=True, headers=True, audit=True, flags=True, maintenance=True,
                  inventory=True,
-                 posture=True, resources=True, proxy=True):
+                 posture=True, resources=True, proxy=True, server_name=None):
         self.core = Core(site_id, secret, endpoint, debug)
         if not self.core.valid:
             print("[analytics-platform] site_id, secret and endpoint are required; nothing is sent and every request passes")
@@ -94,6 +96,14 @@ class Platform:
             opts = dict(setting) if isinstance(setting, dict) else {}
             if name == "firewall":
                 opts.setdefault("trust_proxy", trust_proxy)
+            # server_name names this service for every module that sends one,
+            # so its errors, timings and resources can be told apart.
+            if server_name and name in ("errors", "performance", "crawlers", "resources"):
+                opts.setdefault("server_name", server_name)
+            # Inventory and posture call it host, and are stored one per site
+            # and host: without it two services on one machine overwrite each other's.
+            if server_name and name in ("inventory", "posture"):
+                opts.setdefault("host", server_name)
             try:
                 self._modules[name] = _load(name, self.core, opts)
             except Exception as error:
@@ -144,6 +154,19 @@ class Platform:
         if errors:
             errors.capture_exception(error, request=request, status=status, kind=kind)
 
+    def job(self, name):
+        """A background job (a queue consumer, a cron task), as a decorator or
+        a with block: its errors are sent with the job's name as their route,
+        and each run is timed (Health → Server speed → Jobs); a run that raises
+        counts as failed, and the exception is raised on.
+
+            @platform.job("send-receipts")
+            def send_receipts(): ...
+
+            with platform.job("nightly-import"): ...
+        """
+        return _Job(self, name)
+
     def login_failed(self, request_or_ip):
         """A failed login (bot protection): the address, or a Django, Flask or
         Starlette request (its address as trust_proxy says)."""
@@ -417,6 +440,53 @@ class _Headers:
         pass
 
 
+class _Job:
+    """platform.job(name): a with block (sync or async) or a decorator."""
+
+    def __init__(self, platform, name):
+        self.platform = platform
+        self.name = name
+        self.route = "/(job) " + str(name or "job")[:180]
+        self._runs = []
+
+    def _fields(self):
+        return {"method": "JOB", "path": self.route, "route": self.route, "session_id": ""}
+
+    def __enter__(self):
+        self._runs.append((time.perf_counter(), current_request.set(self._fields)))
+        return self
+
+    def __exit__(self, kind, value, tb):
+        started, token = self._runs.pop()
+        current_request.reset(token)
+        if value is not None and not isinstance(value, Exception):
+            return False  # cancelled or interrupted (CancelledError, KeyboardInterrupt): not a run that failed
+        if value is not None:
+            self.platform.capture_exception(value, status=500, kind="error", request=self._fields())
+        self.platform.time_request("JOB", self.route, 500 if value is not None else 200, started, self.route)
+        return False
+
+    async def __aenter__(self):
+        return self.__enter__()
+
+    async def __aexit__(self, kind, value, tb):
+        return self.__exit__(kind, value, tb)
+
+    def __call__(self, fn):
+        if asyncio.iscoroutinefunction(fn):
+            @functools.wraps(fn)
+            async def run_async(*args, **kwargs):
+                with _Job(self.platform, self.name):
+                    return await fn(*args, **kwargs)
+            return run_async
+
+        @functools.wraps(fn)
+        def run(*args, **kwargs):
+            with _Job(self.platform, self.name):
+                return fn(*args, **kwargs)
+        return run
+
+
 class PlatformMiddleware:
     """ASGI middleware: app.add_middleware(PlatformMiddleware, platform=platform)."""
 
@@ -479,6 +549,13 @@ class PlatformMiddleware:
                     message = dict(message, headers=list(message.get("headers") or []) + [(n.lower().encode(), v.encode("latin-1", "replace")) for n, v in extra] + remember)
             await send(message)
 
+        # Errors captured during the request (logged, or caught without the
+        # request) still know which request they came from. The router sets
+        # scope["route"] on the way in, so it is read when the error is.
+        token = current_request.set(lambda: {
+            "method": scope.get("method", ""), "path": scope.get("path", ""),
+            "route": getattr(scope.get("route"), "path", ""), "session_id": headers.get(SESSION_HEADER, ""),
+        })
         try:
             await self.app(scope, receive, timed_send)
         except Exception as error:
@@ -488,6 +565,7 @@ class PlatformMiddleware:
             })
             raise
         finally:
+            current_request.reset(token)
             # The router sets scope["route"] (FastAPI, Starlette) on the way in.
             self.platform.time_request(scope.get("method", ""), getattr(scope.get("route"), "path", "") or "",
                                        seen["status"], started, scope.get("path", ""))

{analytics_platform-0.2.2 → analytics_platform-0.3.1}/analytics_platform/core.py

@@ -16,7 +16,7 @@ import urllib.error
 import urllib.parse
 import urllib.request
 
-VERSION = "0.2.2"
+VERSION = "0.3.1"
 TIMEOUT = 5
 MIN_SYNC = 30
 RETRY = 60

{analytics_platform-0.2.2 → analytics_platform-0.3.1}/analytics_platform/django.py

@@ -16,6 +16,7 @@ from django.conf import settings
 from django.http import HttpResponse
 
 from . import SESSION_HEADER, Platform
+from .errors import current_request
 
 _platform = None
 
@@ -92,23 +93,34 @@ class PlatformMiddleware:
             for name, value in closed[1]:
                 response[name] = value
             return response
-        response = self.get_response(request)
+        # Errors captured during the request (logged, or caught without the
+        # request) still know which request they came from.
+        token = current_request.set(lambda: _request_fields(request))
+        try:
+            response = self.get_response(request)
+        finally:
+            current_request.reset(token)
         for name, value in self.platform.security_headers(response.headers.keys()):
             response[name] = value
         if closed:
             response["Set-Cookie"] = closed[1][0][1]
-        match = getattr(request, "resolver_match", None)
-        route = getattr(match, "route", "") or ""
-        self.platform.time_request(request.method, ("/" + route.lstrip("^").rstrip("$").lstrip("/")) if route else "",
-                                   response.status_code, started, request.path)
+        self.platform.time_request(request.method, _route(request), response.status_code, started, request.path)
         self.platform.record_crawler(headers.get("user-agent", ""), request.path, response.status_code, started,
                                      response.headers.get("Content-Length") or 0, ip)
         return response
 
     def process_exception(self, request, exception):
-        match = getattr(request, "resolver_match", None)
-        self.platform.capture_exception(exception, status=500, kind="error", request={
-            "method": request.method, "path": request.path, "route": getattr(match, "route", "") or "",
-            "session_id": request.headers.get(SESSION_HEADER, ""),
-        })
+        self.platform.capture_exception(exception, status=500, kind="error", request=_request_fields(request))
         return None
+
+
+# The URL pattern, as Server speed names it, so an error's route and the
+# route's timings match.
+def _route(request):
+    route = getattr(getattr(request, "resolver_match", None), "route", "") or ""
+    return ("/" + route.lstrip("^").rstrip("$").lstrip("/")) if route else ""
+
+
+def _request_fields(request):
+    return {"method": request.method, "path": request.path, "route": _route(request),
+            "session_id": request.headers.get(SESSION_HEADER, "")}

analytics_platform-0.3.1/analytics_platform/errors.py

@@ -0,0 +1,322 @@
+"""Error monitoring module: the server's errors go to the collector (POST
+/events/server-errors), where they join the browser's errors in the Errors
+report. Uncaught exceptions (main thread and other threads) are captured on
+their own and Python still prints and exits as it would. The framework
+integrations capture request errors (5xx); capture_exception() captures
+errors you catch; capture_logging sends the exceptions your code logs. An
+error is sent once however many of those see it. Errors are sent in small
+batches, a batch the collector couldn't take is tried once more, and sending
+never raises. What still can't be sent (the collector is away, or the process
+is crashing) waits in a file and is sent once it can be, after a restart too;
+each error carries when it happened.
+"""
+import contextvars
+import hashlib
+import json
+import logging
+import os
+import tempfile
+import platform as host
+import re
+import socket
+import sys
+import threading
+import time
+import traceback
+from datetime import datetime, timezone
+
+from .core import SESSION_HEADER, Periodic
+from .performance import normalize_route
+
+BATCH = 10
+QUEUE_MAX = 100
+FLUSH_EVERY = 2
+# A batch the collector couldn't take (unreachable, 429, 5xx) is sent once
+# more after this many seconds.
+RETRY_AFTER = 2
+SEEN = "_analytics_platform_sent"
+# The file of errors waiting to be sent: tried again this often (seconds), and
+# kept under this size (past it, new ones are dropped rather than filling a disk).
+RESEND_EVERY = 60
+SPOOL_BYTES = 1024 * 1024
+
+# The request being handled, set by the framework integrations: a callable
+# returning {"method", "path", "route", "session_id"}, so an error captured
+# without a request (logged, or caught deep in your code) still gets its route.
+current_request = contextvars.ContextVar("analytics_platform_request", default=None)
+
+
+def _request_fields():
+    fields = current_request.get()
+    if fields is None:
+        flask = sys.modules.get("flask")
+        if flask is not None and flask.has_request_context():
+            rule = getattr(flask.request, "url_rule", None)
+            return {"method": flask.request.method, "path": flask.request.path, "route": getattr(rule, "rule", ""),
+                    "session_id": flask.request.headers.get(SESSION_HEADER, "")}
+        return None
+    try:
+        return fields()
+    except Exception:
+        return None
+
+
+def _failed(res):
+    return res is None or res.status == 429 or res.status >= 500
+
+
+class _LogHandler(logging.Handler):
+    """Sends the exception of a log record at ERROR or above (logger.exception,
+    or exc_info=True). A record without an exception isn't sent: it has no
+    traceback to group it by."""
+
+    def __init__(self, errors):
+        super().__init__(logging.ERROR)
+        self.errors = errors
+
+    def emit(self, record):
+        exc = record.exc_info[1] if record.exc_info else None
+        if isinstance(exc, BaseException) and not record.name.startswith("analytics_platform"):
+            self.errors.capture_exception(exc, kind="logged")
+
+
+class Errors:
+    """Options: server_name (default the host name), release (which build this
+    is; default the ANALYTICS_RELEASE environment variable), root (paths in tracebacks
+    are made relative to it; default the working directory), capture_uncaught
+    (default True), capture_logging (default False: exceptions logged at
+    ERROR or above through the logging module are sent too),
+    before_send(event, error) to change an event or drop it (return None),
+    spool_dir (where errors that couldn't be sent wait; default the system's
+    temp folder, False to keep none)."""
+
+    def __init__(self, core, server_name=None, root=None, release=None, capture_uncaught=True, before_send=None,
+                 capture_logging=False, spool_dir=None, **_):
+        self.core = core
+        self.server_name = str(server_name or socket.gethostname())[:100]
+        self.root = str(root or os.getcwd()).rstrip("/\\")
+        # Which build this is, for "introduced in" in the Errors report.
+        self.release = re.sub(r"[^\w.+\-]", "", str(release or os.environ.get("ANALYTICS_RELEASE", "")).strip())[:64]
+        self.before_send = before_send
+        self.queue = []
+        self.lock = threading.Lock()
+        # Named after the site and its secret, not the site id alone, so the
+        # folder's listing tells nobody which site it is.
+        self.spool_file = None
+        if spool_dir is not False and core.valid:
+            name = hashlib.sha256(("%s|%s" % (core.site_id, core.secret)).encode()).hexdigest()[:16]
+            self.spool_file = os.path.join(str(spool_dir or tempfile.gettempdir()), "analytics-errors-%s.jsonl" % name)
+        self._last_resend = 0.0
+        # One resend at a time (threads share the file), and what it is still
+        # sending, written back if the process crashes meanwhile.
+        self._resend_lock = threading.Lock()
+        self._resending = []
+        self.job = Periodic(self._flush_job, FLUSH_EVERY) if core.valid else None
+        self._previous = None
+        if capture_uncaught:
+            self._previous = (sys.excepthook, threading.excepthook)
+            sys.excepthook = self._excepthook
+            threading.excepthook = self._thread_excepthook
+        self._log_handler = None
+        if capture_logging:
+            self._log_handler = _LogHandler(self)
+            logging.getLogger().addHandler(self._log_handler)
+
+    def _excepthook(self, kind, value, tb):
+        self.capture_exception(value, kind="error")
+        # The file waits for the next start rather than delaying the exit.
+        self.flush(resend=False)
+        self._keep_resending()
+        self._previous[0](kind, value, tb)
+
+    def _thread_excepthook(self, args):
+        if args.exc_value is not None:
+            self.capture_exception(args.exc_value, kind="error")
+            self.flush(resend=False)
+        self._previous[1](args)
+
+    def _keep_resending(self):
+        """The process is exiting: what a resend hasn't sent yet goes back in the file."""
+        with self.lock:
+            left, self._resending = self._resending, []
+        self._spool(left)
+
+    def _relative(self, stack):
+        return stack.replace(self.root + os.sep, "").replace(self.root + "/", "") if self.root else stack
+
+    def capture_exception(self, error, request=None, status=0, kind="handled"):
+        """request: {"method", "path", "route", "session_id"} (the integrations fill it in)."""
+        if not self.core.is_on("errors"):
+            return
+        try:
+            is_error = isinstance(error, BaseException)
+            if request is None:
+                request = _request_fields()
+            # The framework, your handler and logging can all see one error:
+            # sent once, and a later capture fills in the event while it waits.
+            if is_error and getattr(error, SEEN, None) is not None:
+                self._upgrade(error, getattr(error, SEEN), request, status, kind)
+                return
+            stack = "".join(traceback.format_exception(type(error), error, error.__traceback__)) if is_error else ""
+            event = {
+                "message": str(error) or (type(error).__name__ if is_error else "Unknown error"),
+                "error_type": type(error).__name__ if is_error else "Error",
+                "stack": self._relative(stack),
+                "kind": kind,
+                "status_code": int(status or 0),
+                "runtime": "Python",
+                "runtime_version": host.python_version(),
+                "os": sys.platform,
+                "server_name": self.server_name,
+                "release": self.release,
+                # When it happened: a crash sent after a restart keeps its own time.
+                "at": datetime.now(timezone.utc).isoformat(timespec="milliseconds").replace("+00:00", "Z"),
+            }
+            event.update({k: str(v or "") for k, v in (request or {}).items() if k in ("method", "path", "route", "session_id")})
+            if event.get("path"):
+                event["path"] = event["path"].split("?")[0]
+                # Named as Server speed names the request, so the two match.
+                if not event.get("route"):
+                    event["route"] = normalize_route(event["path"])
+            if self.before_send:
+                event = self.before_send(event, error)
+                if not event:
+                    return
+            with self.lock:
+                if len(self.queue) >= QUEUE_MAX:
+                    self.core.log("errors", "queue full, error dropped")
+                    return
+                self.queue.append(event)
+                full = len(self.queue) >= BATCH
+            if is_error:
+                try:
+                    setattr(error, SEEN, event)
+                except Exception:
+                    pass
+            if full and self.job:
+                self.job.run_now()
+        except Exception as failure:
+            self.core.log("errors", "could not capture error:", failure)
+
+    def _upgrade(self, error, waiting, request, status, kind):
+        """An exception logged and then raised on is captured first as
+        "logged", with no status; the framework's capture that follows knows
+        the status, the kind and the request."""
+        if kind == "logged":
+            return
+        with self.lock:
+            index = next((i for i, queued in enumerate(self.queue) if queued is waiting), -1)
+            if index == -1:
+                return
+            event = dict(waiting, kind=kind if waiting.get("kind") == "logged" else waiting.get("kind"),
+                         status_code=waiting.get("status_code") or int(status or 0))
+            for key in ("method", "path", "route", "session_id"):
+                if not event.get(key) and (request or {}).get(key):
+                    event[key] = str(request[key])
+            if event.get("path"):
+                event["path"] = event["path"].split("?")[0]
+            if self.before_send:
+                event = self.before_send(event, error)
+            if event:
+                self.queue[index] = event
+                setattr(error, SEEN, event)
+            else:
+                del self.queue[index]
+
+    def flush(self, resend=True):
+        with self.lock:
+            waiting, self.queue = self.queue, []
+        sent = True
+        for i in range(0, len(waiting), BATCH):
+            body = {"errors": waiting[i:i + BATCH]}
+            res = self.core.send("errors", "/events/server-errors", body=body)
+            if _failed(res):
+                time.sleep(RETRY_AFTER)
+                res = self.core.send("errors", "/events/server-errors", body=body)
+            if _failed(res):
+                sent = False
+                self._spool(body["errors"])
+        # Not straight after the collector failed this flush: it would only
+        # wait out another timeout.
+        if resend and sent and self.spool_file and time.time() - self._last_resend >= RESEND_EVERY:
+            self.resend()
+
+    def _spool(self, events):
+        """Appends events to the file. Credentials are added when sent, never written down."""
+        if not self.spool_file or not events:
+            return
+        try:
+            if os.path.exists(self.spool_file) and os.path.getsize(self.spool_file) > SPOOL_BYTES:
+                self.core.log("errors", "waiting errors file is full, errors dropped")
+                return
+            fd = os.open(self.spool_file, os.O_WRONLY | os.O_CREAT | os.O_APPEND, 0o600)
+            with os.fdopen(fd, "a", encoding="utf-8") as out:
+                out.write("".join(json.dumps(event) + "\n" for event in events))
+        except Exception as failure:
+            self.core.log("errors", "could not keep errors to send later:", failure)
+
+    def resend(self):
+        """Sends what earlier attempts (or an earlier run) couldn't. Taken by
+        renaming the file first, so two processes never send the same errors."""
+        self._last_resend = time.time()
+        if not self.spool_file or not self._resend_lock.acquire(blocking=False):
+            return
+        try:
+            self._resend()
+        finally:
+            self._resend_lock.release()
+
+    def _resend(self):
+        taken = "%s.%d.%d.sending" % (self.spool_file, os.getpid(), threading.get_ident())
+        try:
+            os.replace(self.spool_file, taken)
+        except OSError:
+            return  # nothing waiting
+        events = []
+        try:
+            with open(taken, encoding="utf-8") as waiting:
+                for line in waiting:
+                    try:
+                        event = json.loads(line)
+                    except ValueError:
+                        continue
+                    if isinstance(event, dict):
+                        events.append(event)
+        finally:
+            try:
+                os.remove(taken)
+            except OSError:
+                pass
+        with self.lock:
+            self._resending = events
+        while True:
+            with self.lock:
+                if self._resending is not events or not events:
+                    break  # all sent, or written back by a crash
+                batch = events[:BATCH]
+            if _failed(self.core.send("errors", "/events/server-errors", body={"errors": batch})):
+                with self.lock:
+                    left = events if self._resending is events else []
+                    self._resending = []
+                self._spool(left)
+                return
+            with self.lock:
+                del events[:len(batch)]
+        with self.lock:
+            if self._resending is events:
+                self._resending = []
+
+    def _flush_job(self):
+        self.flush()
+        return FLUSH_EVERY
+
+    def close(self):
+        if self.job:
+            self.job.stop()
+        if self._previous:
+            sys.excepthook, threading.excepthook = self._previous
+            self._previous = None
+        if self._log_handler:
+            logging.getLogger().removeHandler(self._log_handler)
+            self._log_handler = None
+        self.flush()

{analytics_platform-0.2.2 → analytics_platform-0.3.1}/analytics_platform/proxy.py

@@ -47,6 +47,13 @@ def prefix_for(secret):
     return hashlib.sha256(("proxy|" + str(secret)).encode("utf-8")).hexdigest()[:8]
 
 
+# Sent as X-Proxy-Key, so the collector believes the visitor addresses this
+# proxy passes on: anyone can write X-Forwarded-For. Worked out from the secret
+# as the collector does (expresscollect/utils/proxyKey.js).
+def key_for(secret):
+    return hashlib.sha256(("proxykey|" + str(secret)).encode("utf-8")).hexdigest()[:32]
+
+
 class Proxy:
     """prefix: the path it answers on (default: from the secret)."""
 
@@ -54,6 +61,7 @@ class Proxy:
         self.core = core
         self.enabled = enabled
         self.prefix = re.sub(r"[^A-Za-z0-9_-]", "", str(prefix or prefix_for(core.secret)))
+        self.key = key_for(core.secret) if core.secret else ""
         # One copy of each tracker file, so a repeat visitor costs no upstream
         # request. A handful of small files: it never grows.
         self._files = {}
@@ -139,6 +147,8 @@ class Proxy:
         # The visitor's address: the collector needs it for the country, the
         # daily visitor ID and the per-visitor rate limit.
         out = {"X-Forwarded-For": client_ip or ""}
+        if self.key:
+            out["X-Proxy-Key"] = self.key
         for name in PASS_HEADERS:
             value = headers.get(name)
             if value:

{analytics_platform-0.2.2 → analytics_platform-0.3.1}/analytics_platform.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: analytics-platform
-Version: 0.2.2
+Version: 0.3.1
 Summary: Firewall, error monitoring and server analytics for your Python server, run from your analytics dashboard.
 Author: steviec87
 License-Expression: MIT
@@ -158,8 +158,40 @@ except PaymentError as error:
     raise
 ```
 
+Exceptions your code only logs: `errors={"capture_logging": True}` sends an
+exception logged at ERROR or above (`logger.exception(...)`, or
+`exc_info=True`); it is still logged. An exception is sent once however many
+of these see it, and one logged inside a Django, Flask or ASGI request keeps
+that request's route. A batch the collector couldn't take is tried once more
+a few seconds later.
+
+What still can't be sent waits in a file in the temp folder and is sent when
+it can be, after a restart too; each error keeps the time it happened.
+
+Background jobs, as a decorator or a `with` block (sync or async):
+
+```python
+@platform.job("send-receipts")
+def send_receipts(): ...
+```
+
+Their errors carry the job's name as the route, a job that raises is sent
+(status 500) and raised on, and each run is timed (Server speed → Jobs).
+Several services on one site: `Platform(..., server_name="worker")`.
+
+**Several apps on one site** (microservices, a worker, a Node service next to
+this one): install the package in each, with the same `site_id`, `secret` and
+`endpoint`, and a `server_name` of its own. Errors, Server speed, Crawlers and
+Security → Updates then tell the apps apart. Without one, each app is named
+after its machine: two apps on one machine are reported as one, and only the
+last package list sent is kept. A service only your other apps call takes
+`firewall=False, proxy=False, maintenance=False` (its requests all come from
+your own apps, so the rate limit would see one visitor); on a machine shared
+by several apps, keep `resources` on in only one of them.
+
 Options: `server_name`, `root` (traceback paths relative to it),
-`capture_uncaught`, `before_send(event, error)` (change an error, or return
+`capture_uncaught`, `capture_logging`, `spool_dir` (where unsent errors wait;
+`False` for none), `before_send(event, error)` (change an error, or return
 `None` to drop it).
 
 ## Server analytics

{analytics_platform-0.2.2 → analytics_platform-0.3.1}/analytics_platform.egg-info/SOURCES.txt

@@ -23,6 +23,7 @@ analytics_platform.egg-info/SOURCES.txt
 analytics_platform.egg-info/dependency_links.txt
 analytics_platform.egg-info/top_level.txt
 tests/test_crawlers.py
+tests/test_errors.py
 tests/test_firewall.py
 tests/test_proxy.py
 tests/test_request_rules.py

{analytics_platform-0.2.2 → analytics_platform-0.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "analytics-platform"
-version = "0.2.2"
+version = "0.3.1"
 description = "Firewall, error monitoring and server analytics for your Python server, run from your analytics dashboard."
 readme = "README.md"
 requires-python = ">=3.8"

analytics_platform-0.3.1/tests/test_errors.py

@@ -0,0 +1,253 @@
+"""The errors module: an error is sent once however many handlers see it,
+exceptions logged through logging are sent when asked, a request's route
+follows errors captured without it, and a failed batch is tried once more.
+
+    python3 -m unittest discover -s tests
+"""
+import json
+import logging
+import os
+import sys
+import unittest
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+
+from analytics_platform import errors as mod  # noqa: E402
+from analytics_platform.errors import Errors, current_request  # noqa: E402
+
+
+class Answer:
+    def __init__(self, status):
+        self.status = status
+
+
+class FakeCore:
+    valid = False  # no background job: the tests flush by hand
+
+    def __init__(self, answers=None):
+        self.answers = list(answers or [])
+        self.sent = []
+
+    def is_on(self, name):
+        return True
+
+    def log(self, *args):
+        pass
+
+    def send(self, module, path, body=None, **_):
+        self.sent.append(body["errors"])
+        status = self.answers.pop(0) if self.answers else 202
+        return None if status is None else Answer(status)
+
+
+def events(core):
+    return [event for batch in core.sent for event in batch]
+
+
+class ErrorsTest(unittest.TestCase):
+    def setUp(self):
+        self.retry = mod.RETRY_AFTER
+        mod.RETRY_AFTER = 0
+
+    def tearDown(self):
+        mod.RETRY_AFTER = self.retry
+
+    def test_one_error_is_sent_once(self):
+        core = FakeCore()
+        errors = Errors(core, capture_uncaught=False)
+        error = ValueError("payment failed")
+        errors.capture_exception(error, status=500, kind="error")
+        errors.capture_exception(error)
+        errors.capture_exception(ValueError("payment failed"))
+        errors.close()
+        self.assertEqual(len(events(core)), 2)
+
+    def test_capture_logging_sends_logged_exceptions_only_when_on(self):
+        logger = logging.getLogger("shop.checkout")
+        quiet = logging.NullHandler()  # keeps logging's last-resort printer out of the test output
+        logger.addHandler(quiet)
+        try:
+            core = FakeCore()
+            off = Errors(core, capture_uncaught=False)
+            try:
+                raise RuntimeError("off")
+            except RuntimeError:
+                logger.exception("not sent")
+            off.close()
+            self.assertEqual(core.sent, [])
+
+            on = Errors(core, capture_uncaught=False, capture_logging=True)
+            try:
+                raise RuntimeError("card declined")
+            except RuntimeError:
+                logger.exception("charge failed")
+            logger.error("plain text is not sent")
+            on.close()
+            sent = events(core)
+            self.assertEqual(len(sent), 1)
+            self.assertEqual(sent[0]["message"], "card declined")
+            self.assertEqual(sent[0]["kind"], "logged")
+            self.assertNotIn(on._log_handler, logging.getLogger().handlers)
+        finally:
+            logger.removeHandler(quiet)
+
+    def test_the_current_request_fills_in_an_error_captured_without_one(self):
+        core = FakeCore()
+        errors = Errors(core, capture_uncaught=False)
+        token = current_request.set(lambda: {"method": "POST", "path": "/orders/12", "route": "/orders/<int:id>"})
+        try:
+            errors.capture_exception(ValueError("deep inside"))
+        finally:
+            current_request.reset(token)
+        errors.capture_exception(ValueError("outside"))
+        errors.close()
+        inside, outside = events(core)
+        self.assertEqual(inside["route"], "/orders/<int:id>")
+        self.assertEqual(inside["method"], "POST")
+        self.assertNotIn("route", outside)
+
+    def test_a_failed_batch_is_sent_once_more_and_only_once(self):
+        for answers, expected in (([503, 503], 2), ([None, 202], 2), ([400], 1)):
+            core = FakeCore(answers)
+            errors = Errors(core, capture_uncaught=False)
+            errors.capture_exception(ValueError("x"))
+            errors.flush()
+            self.assertEqual(len(core.sent), expected, answers)
+
+
+    def test_an_exception_logged_then_raised_keeps_the_frameworks_status_and_request(self):
+        logger = logging.getLogger("shop.pay")
+        quiet = logging.NullHandler()
+        logger.addHandler(quiet)
+        try:
+            core = FakeCore()
+            errors = Errors(core, capture_uncaught=False, capture_logging=True)
+            try:
+                raise RuntimeError("charge failed")
+            except RuntimeError as error:
+                logger.exception("charge failed")
+                errors.capture_exception(error, status=500, kind="error",
+                                         request={"method": "POST", "path": "/pay", "route": "/pay"})
+            errors.close()
+            sent = events(core)
+            self.assertEqual(len(sent), 1)
+            self.assertEqual((sent[0]["kind"], sent[0]["status_code"], sent[0]["route"]), ("error", 500, "/pay"))
+        finally:
+            logger.removeHandler(quiet)
+
+    def test_without_a_route_an_error_is_named_as_server_speed_names_the_request(self):
+        core = FakeCore()
+        errors = Errors(core, capture_uncaught=False)
+        errors.capture_exception(ValueError("x"), request={"method": "GET", "path": "/orders/123/items?x=1"})
+        errors.close()
+        self.assertEqual(events(core)[0]["route"], "/orders/:id/items")
+
+    def test_errors_the_collector_could_not_take_wait_in_a_file_and_are_sent_later(self):
+        import tempfile
+        import shutil
+        folder = tempfile.mkdtemp()
+        try:
+            core = FakeCore([503, 503])
+            core.valid, core.site_id, core.secret = True, "a1b2c3d4e5f6a1b2c3d4e5f6", "s"
+            errors = Errors(core, capture_uncaught=False, spool_dir=folder)
+            errors.job.stop()  # flushed by hand
+            errors._last_resend = 10 ** 12  # no resend inside this flush
+            errors.capture_exception(ValueError("collector away"))
+            errors.flush()
+            files = os.listdir(folder)
+            self.assertEqual(len(files), 1)
+            kept = open(os.path.join(folder, files[0])).read()
+            self.assertIn("collector away", kept)
+            self.assertNotIn("a1b2c3d4e5f6a1b2c3d4e5f6", kept + files[0])
+            self.assertRegex(kept, r'"at": "\d{4}-\d\d-\d\dT[^"]+Z"')
+            core.sent = []
+            errors.resend()
+            self.assertEqual(events(core)[0]["message"], "collector away")
+            self.assertEqual(os.listdir(folder), [])
+        finally:
+            shutil.rmtree(folder, ignore_errors=True)
+
+    def test_a_job_names_its_errors_and_sends_the_one_it_raises(self):
+        from analytics_platform import _Job
+
+        class FakePlatform:
+            def __init__(self, errors):
+                self.errors, self.timed = errors, []
+
+            def capture_exception(self, error, **kwargs):
+                self.errors.capture_exception(error, **kwargs)
+
+            def time_request(self, method, route, status, started, path=""):
+                self.timed.append((method, route, status))
+
+        core = FakeCore()
+        errors = Errors(core, capture_uncaught=False)
+        platform = FakePlatform(errors)
+
+        @_Job(platform, "receipts")
+        def receipts():
+            errors.capture_exception(ValueError("one receipt failed"))
+            raise RuntimeError("the job failed")
+
+        with self.assertRaises(RuntimeError):
+            receipts()
+        errors.close()
+        inside, raised = events(core)
+        self.assertEqual((inside["method"], inside["route"]), ("JOB", "/(job) receipts"))
+        self.assertEqual(raised["status_code"], 500)
+        self.assertEqual(platform.timed, [("JOB", "/(job) receipts", 500)])
+
+        # Cancelled, not failed: neither sent nor timed.
+        import asyncio
+        with self.assertRaises(asyncio.CancelledError):
+            with _Job(platform, "receipts"):
+                raise asyncio.CancelledError()
+        self.assertEqual(len(platform.timed), 1)
+
+    def spooling(self, answers):
+        import tempfile
+        import shutil
+        folder = tempfile.mkdtemp()
+        self.addCleanup(shutil.rmtree, folder, True)
+        core = FakeCore(answers)
+        core.valid, core.site_id, core.secret = True, "a1b2c3d4e5f6a1b2c3d4e5f6", "s"
+        errors = Errors(core, capture_uncaught=False, spool_dir=folder)
+        errors.job.stop()  # flushed by hand
+        return core, errors
+
+    def test_a_flush_whose_own_sends_failed_does_not_resend_straight_after(self):
+        core, errors = self.spooling([503, 503])
+        errors.capture_exception(ValueError("collector away"))
+        errors.flush()
+        self.assertEqual(len(core.sent), 2, "the send and its one retry, no resend of the file")
+        self.assertTrue(os.path.exists(errors.spool_file))
+
+    def test_one_resend_at_a_time(self):
+        core, errors = self.spooling([503, 503])
+        errors._last_resend = 10 ** 12
+        errors.capture_exception(ValueError("waiting"))
+        errors.flush()
+        core.sent = []
+        with errors._resend_lock:
+            errors.resend()  # another thread is resending
+        self.assertEqual(core.sent, [])
+        self.assertTrue(os.path.exists(errors.spool_file))
+
+    def test_errors_being_resent_when_the_process_crashes_go_back_in_the_file(self):
+        core, errors = self.spooling([])
+        errors._spool([{"message": "e%d" % i} for i in range(12)])
+        calls = []
+
+        def send(module, path, body=None, **_):
+            calls.append(body["errors"])
+            if len(calls) == 1:
+                return Answer(202)
+            errors._keep_resending()  # the crash, while the second batch is out
+            return None
+        core.send = send
+        errors.resend()
+        kept = open(errors.spool_file).read().splitlines()
+        self.assertEqual([json.loads(line)["message"] for line in kept], ["e10", "e11"], "once, and not what was sent")
+
+if __name__ == "__main__":
+    unittest.main()

{analytics_platform-0.2.2 → analytics_platform-0.3.1}/tests/test_proxy.py

@@ -12,7 +12,7 @@ from http.server import BaseHTTPRequestHandler, HTTPServer
 
 sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
 
-from analytics_platform.proxy import Proxy, prefix_for  # noqa: E402
+from analytics_platform.proxy import Proxy, key_for, prefix_for  # noqa: E402
 
 TRACKER = b"// a tracker" + b"x" * 600
 
@@ -77,6 +77,10 @@ class ProxyTest(unittest.TestCase):
         Collector.seen = []
         self.proxy = Proxy(FakeCore(self.endpoint))
 
+    def test_the_proxy_key_is_worked_out_as_the_collector_does(self):
+        # The same vector is pinned in the collector, the backend and the other packages.
+        self.assertEqual(key_for("0123456789abcdef01234567"), "8fc74dbbd4f088449862841cd29fcaee")
+
     def test_the_address_comes_from_the_secret(self):
         self.assertEqual(prefix_for("s3cret"), prefix_for("s3cret"))
         self.assertNotEqual(prefix_for("s3cret"), prefix_for("other"))
@@ -123,6 +127,7 @@ class ProxyTest(unittest.TestCase):
         self.assertEqual(got["path"], "/collectanalytics/e?v=1")
         self.assertEqual(got["body"], b'{"event":"pageview"}')
         self.assertEqual(got["headers"].get("X-Forwarded-For"), "198.51.100.4")
+        self.assertEqual(got["headers"].get("X-Proxy-Key"), key_for("s3cret"), "so the collector believes the address")
         self.assertEqual(got["headers"].get("User-Agent"), "Mozilla/5.0")
         self.assertIsNone(got["headers"].get("Cookie"), "the site's own cookies stay on the site")
 

analytics_platform-0.2.2/analytics_platform/errors.py

@@ -1,113 +0,0 @@
-"""Error monitoring module: the server's errors go to the collector (POST
-/events/server-errors), where they join the browser's errors in the Errors
-report. Uncaught exceptions (main thread and other threads) are captured on
-their own and Python still prints and exits as it would. The framework
-integrations capture request errors (5xx); capture_exception() captures
-errors you catch. Errors are sent in small batches; sending never raises.
-"""
-import os
-import platform as host
-import re
-import socket
-import sys
-import threading
-import traceback
-
-from .core import Periodic
-
-BATCH = 10
-QUEUE_MAX = 100
-FLUSH_EVERY = 2
-
-
-class Errors:
-    """Options: server_name (default the host name), release (which build this
-    is; default the ANALYTICS_RELEASE environment variable), root (paths in tracebacks
-    are made relative to it; default the working directory), capture_uncaught
-    (default True), before_send(event, error) to change an event or drop it
-    (return None)."""
-
-    def __init__(self, core, server_name=None, root=None, release=None, capture_uncaught=True, before_send=None, **_):
-        self.core = core
-        self.server_name = str(server_name or socket.gethostname())[:100]
-        self.root = str(root or os.getcwd()).rstrip("/\\")
-        # Which build this is, for "introduced in" in the Errors report.
-        self.release = re.sub(r"[^\w.+\-]", "", str(release or os.environ.get("ANALYTICS_RELEASE", "")).strip())[:64]
-        self.before_send = before_send
-        self.queue = []
-        self.lock = threading.Lock()
-        self.job = Periodic(self._flush_job, FLUSH_EVERY) if core.valid else None
-        self._previous = None
-        if capture_uncaught:
-            self._previous = (sys.excepthook, threading.excepthook)
-            sys.excepthook = self._excepthook
-            threading.excepthook = self._thread_excepthook
-
-    def _excepthook(self, kind, value, tb):
-        self.capture_exception(value, kind="error")
-        self.flush()
-        self._previous[0](kind, value, tb)
-
-    def _thread_excepthook(self, args):
-        if args.exc_value is not None:
-            self.capture_exception(args.exc_value, kind="error")
-            self.flush()
-        self._previous[1](args)
-
-    def _relative(self, stack):
-        return stack.replace(self.root + os.sep, "").replace(self.root + "/", "") if self.root else stack
-
-    def capture_exception(self, error, request=None, status=0, kind="handled"):
-        """request: {"method", "path", "route", "session_id"} (the integrations fill it in)."""
-        if not self.core.is_on("errors"):
-            return
-        try:
-            is_error = isinstance(error, BaseException)
-            stack = "".join(traceback.format_exception(type(error), error, error.__traceback__)) if is_error else ""
-            event = {
-                "message": str(error) or (type(error).__name__ if is_error else "Unknown error"),
-                "error_type": type(error).__name__ if is_error else "Error",
-                "stack": self._relative(stack),
-                "kind": kind,
-                "status_code": int(status or 0),
-                "runtime": "Python",
-                "runtime_version": host.python_version(),
-                "os": sys.platform,
-                "server_name": self.server_name,
-                "release": self.release,
-            }
-            event.update({k: str(v or "") for k, v in (request or {}).items() if k in ("method", "path", "route", "session_id")})
-            if event.get("path"):
-                event["path"] = event["path"].split("?")[0]
-            if self.before_send:
-                event = self.before_send(event, error)
-                if not event:
-                    return
-            with self.lock:
-                if len(self.queue) >= QUEUE_MAX:
-                    self.core.log("errors", "queue full, error dropped")
-                    return
-                self.queue.append(event)
-                full = len(self.queue) >= BATCH
-            if full and self.job:
-                self.job.run_now()
-        except Exception as failure:
-            self.core.log("errors", "could not capture error:", failure)
-
-    def flush(self):
-        with self.lock:
-            waiting, self.queue = self.queue, []
-        for i in range(0, len(waiting), BATCH):
-            self.core.send("errors", "/events/server-errors", body={"errors": waiting[i:i + BATCH]})
-
-    def _flush_job(self):
-        self.flush()
-        return FLUSH_EVERY
-
-    def close(self):
-        if self.job:
-            self.job.stop()
-        if self._previous:
-            sys.excepthook, threading.excepthook = self._previous
-            self._previous = None
-        self.flush()