analytics-platform 0.2.1__py3-none-any.whl

analytics_platform/resources.py

@@ -0,0 +1,471 @@
+"""How the machine is doing (protocol in sdk/protocols/resources.md).
+
+CPU, load, memory, swap and disks, sampled every minute and sent to
+POST /events/resources every few minutes. The companion of the performance
+module: that says how the requests went, this says whether the box can still
+serve them, so the dashboard shows what you would otherwise run node_exporter,
+Prometheus and Grafana for.
+
+Nothing is guessed. A reading this machine won't give us is left out of the
+row, never sent as a zero: the collector stores it as NULL and the dashboard
+shows "-", because "0% CPU" and "we couldn't measure CPU" are different
+statements and only one of them means healthy.
+
+Standard library only, like the rest of the package: no psutil.
+"""
+
+import os
+import re
+import socket
+import threading
+from datetime import datetime, timezone
+
+from .core import Periodic
+
+# Keep in step with the collector (expresscollect/Analytics/resources.py) and
+# the agent (sdk/vps-agent).
+SAMPLE_EVERY = 60
+EVERY = 5 * 60
+RETRY_EVERY = 60
+OFF_EVERY = 600
+# About 8 hours of samples: enough to ride out a collector outage, bounded so
+# a long one can't grow in memory.
+MAX_ROWS = 500
+MAX_DISKS = 20
+# Nobody watches a sub-gigabyte partition fill up; this drops the EFI
+# partition and other small mounts without needing a list of paths.
+MIN_DISK_MB = 1024
+# Below this, two CPU readings are too close together to divide: the counters
+# move in ticks, so a percentage over a few milliseconds is quantisation noise
+# (0% or 100%, nothing between).
+MIN_CPU_SECONDS = 1.0
+# Real on-disk filesystems only: no tmpfs, devtmpfs, proc, sysfs, cgroup or
+# squashfs (snaps), none of which are the customer's disk. overlay is here so
+# a containerised app still reports something sensible.
+FSTYPES = {"ext2", "ext3", "ext4", "xfs", "btrfs", "zfs", "f2fs", "jfs",
+           "reiserfs", "ufs", "vfat", "exfat", "ntfs", "ntfs3", "overlay", "apfs", "hfs"}
+
+MB = 1024 * 1024
+
+
+def read_text(path, limit=65536):
+    try:
+        with open(path, "rb") as handle:
+            return handle.read(limit).decode("utf-8", "replace")
+    except OSError:
+        return ""
+
+
+# Sectors in /proc/diskstats are always 512 bytes: the unit of that interface,
+# not of the drive.
+IO_SECTOR = 512
+# Two readings further apart than this say nothing about this minute. It is the
+# rule that matters most here: this client only samples while a request is
+# being served, so the pair can be an hour apart on a quiet site.
+IO_MAX_PAIR_SECONDS = 300
+# Not disks: loop and ram devices, optical drives, device-mapper and md, each
+# of which would count what is underneath it a second time.
+IO_NOT_A_DISK = re.compile(r"^(?:loop|ram|zram|sr|fd|dm-|md\d)")
+# Partitions, which must not be counted alongside their disk.
+IO_PARTITION = re.compile(r"^(?:(?:sd|vd|xvd|hd)[a-z]+\d+|(?:nvme\d+n\d+|mmcblk\d+)p\d+)$")
+# Loopback and the virtual ends of container and VM networking.
+NET_NOT_REAL = re.compile(r"^(?:lo|veth|docker|br-|virbr|tap|tun|vnet)")
+
+
+def cpu_fields(text):
+    """The jiffie counters from /proc/stat's first line, or None.
+
+    In order: user, nice, system, idle, iowait, irq, softirq, steal."""
+    for line in text.splitlines():
+        if not line.startswith("cpu "):
+            continue
+        try:
+            fields = [int(value) for value in line.split()[1:]]
+        except ValueError:
+            return None
+        return fields if len(fields) >= 4 else None
+    return None
+
+
+def cpu_times_of(fields):
+    """(busy, total) jiffies from the counters, for cpu_percent."""
+    total = sum(fields)
+    idle = fields[3] + (fields[4] if len(fields) > 4 else 0)
+    return total - idle, total
+
+
+def cpu_times(text):
+    """(busy, total) jiffies from /proc/stat's first line, or None.
+
+    idle and iowait are the machine doing nothing; everything else, steal
+    included, is time it wasn't available to us."""
+    fields = cpu_fields(text)
+    return None if fields is None else cpu_times_of(fields)
+
+
+# user folds nice in, as top adds them together. Each is a share of the whole
+# interval, so with idle and the interrupt buckets they come to 100.
+CPU_SHARES = (
+    ("cpu_user_pct", (0, 1)),
+    ("cpu_system_pct", (2,)),
+    ("cpu_iowait_pct", (4,)),
+    ("cpu_steal_pct", (7,)),
+)
+
+
+def cpu_shares(before, after):
+    """Where the machine's time went between two /proc/stat readings.
+
+    Empty when the pair can't say, and a column the kernel is too old to carry
+    is left out rather than sent as a zero. steal is the one worth surfacing:
+    time the hypervisor gave to another tenant, which no tuning of the app
+    will change."""
+    if not before or not after:
+        return {}
+    total = sum(after) - sum(before)
+    if total <= 0:
+        return {}
+    out = {}
+    for name, columns in CPU_SHARES:
+        if any(i >= len(before) or i >= len(after) for i in columns):
+            continue
+        moved = sum(after[i] - before[i] for i in columns)
+        if moved < 0:
+            return {}
+        out[name] = round(min(100.0, 100.0 * moved / total), 1)
+    return out
+
+
+def disk_counters(text):
+    """(bytes read, bytes written) since boot over the real disks, or None."""
+    read = written = 0
+    found = False
+    for line in text.splitlines():
+        fields = line.split()
+        if len(fields) < 10:
+            continue
+        name = fields[2]
+        if IO_NOT_A_DISK.match(name) or IO_PARTITION.match(name):
+            continue
+        try:
+            read += int(fields[5]) * IO_SECTOR
+            written += int(fields[9]) * IO_SECTOR
+        except ValueError:
+            continue
+        found = True
+    return (read, written) if found else None
+
+
+def net_counters(text):
+    """(bytes in, bytes out) since boot over the real interfaces, or None."""
+    rx = tx = 0
+    found = False
+    for line in text.splitlines():
+        if ":" not in line:
+            continue
+        name, rest = line.split(":", 1)
+        name = name.strip()
+        if not name or NET_NOT_REAL.match(name):
+            continue
+        fields = rest.split()
+        if len(fields) < 9:
+            continue
+        try:
+            rx += int(fields[0])
+            tx += int(fields[8])
+        except ValueError:
+            continue
+        found = True
+    return (rx, tx) if found else None
+
+
+def rate_mbs(before, after, seconds):
+    """Megabytes a second between two byte counters, or None when the pair
+    can't say: no pair, a reboot that reset them, no time, or too long a gap
+    to call it a rate for this minute."""
+    if before is None or after is None:
+        return None
+    if seconds <= 0 or seconds > IO_MAX_PAIR_SECONDS:
+        return None
+    moved = after - before
+    if moved < 0:
+        return None
+    return round(moved / seconds / MB, 1)
+
+
+def cpu_percent(before, after):
+    """How busy the machine was between two readings, or None when the pair
+    can't say: the first sample, a counter reset, or no time passed."""
+    if not before or not after:
+        return None
+    busy, total = after[0] - before[0], after[1] - before[1]
+    if total <= 0 or busy < 0:
+        return None
+    return round(min(100.0, 100.0 * busy / total), 1)
+
+
+def memory_mb(text):
+    """MemTotal/MemAvailable/Swap from /proc/meminfo, in whole megabytes.
+
+    Used is total - MemAvailable, never total - MemFree: page cache is not
+    pressure, and counting it as used makes every healthy Linux box look full.
+    A field the kernel didn't give us is left out of the result."""
+    values = {}
+    for line in text.splitlines():
+        name, _, rest = line.partition(":")
+        fields = rest.split()
+        if not fields:
+            continue
+        try:
+            values[name] = int(fields[0]) // 1024  # kB -> MB
+        except ValueError:
+            continue
+    out = {}
+    if "MemTotal" in values:
+        out["mem_total_mb"] = values["MemTotal"]
+        if "MemAvailable" in values:
+            out["mem_used_mb"] = max(0, values["MemTotal"] - values["MemAvailable"])
+    if "SwapTotal" in values:
+        out["swap_total_mb"] = values["SwapTotal"]
+        if "SwapFree" in values:
+            out["swap_used_mb"] = max(0, values["SwapTotal"] - values["SwapFree"])
+    return out
+
+
+def mount_points(mounts_text, is_dir=None):
+    """The real disks behind /proc/mounts, one per device under its shortest
+    mount point, so a bind mount isn't reported as a second disk. Off Linux
+    there is no mount table, so the one filesystem we can name without
+    guessing is the one the application runs from.
+
+    A mount point has to be a directory. Docker bind-mounts single files, so a
+    container lists /etc/hosts, /etc/hostname and /etc/resolv.conf on the
+    host's own device, and those paths are short enough to win the
+    shortest-path race against the real mount. The test is per-device and
+    advisory: a device whose mounts cannot be confirmed keeps its shortest
+    one, because reporting no disks is worse than an odd mount point."""
+    if not mounts_text:
+        return [os.path.abspath(os.sep)]
+    is_dir = is_dir or os.path.isdir
+    dirs, any_mount = {}, {}
+    for line in mounts_text.splitlines():
+        fields = line.split()
+        if len(fields) < 3:
+            continue
+        device, mount, fstype = fields[0], fields[1].replace("\\040", " "), fields[2]
+        if fstype not in FSTYPES or not mount.startswith("/"):
+            continue
+        if device not in any_mount or len(mount) < len(any_mount[device]):
+            any_mount[device] = mount
+        try:
+            confirmed = is_dir(mount)
+        except OSError:
+            confirmed = False
+        if confirmed and (device not in dirs or len(mount) < len(dirs[device])):
+            dirs[device] = mount
+    return sorted({dirs.get(d, m) for d, m in any_mount.items()})
+
+
+def disk_rows(points, statvfs=None):
+    """Both figures are df's, so a customer can check them: used is total
+    minus free, and total is used plus what's available to us. The blocks
+    reserved for root are in neither, which is what makes used/total the
+    percentage df prints - and that percentage is what the disk alert is
+    about."""
+    statvfs = statvfs or getattr(os, "statvfs", None)
+    if statvfs is None:
+        return []
+    # One filesystem can sit behind two devices the kernel calls different: in
+    # a container / is the overlay and a bind mount exposes the host disk the
+    # overlay's upperdir lives on, so both report the same size and the same
+    # free space down to the byte. No device-based rule separates them, so the
+    # sizes are what gives it away. Raw bytes, not rounded megabytes, so disks
+    # that merely round alike stay apart; two separate but identically sized
+    # and identically empty filesystems do collapse into one until something
+    # is written to either, and being empty they owe the fullness alert
+    # nothing.
+    seen = set()
+    rows = []
+    for mount in points:
+        try:
+            st = statvfs(mount)
+        except OSError:
+            continue
+        block = st.f_frsize or st.f_bsize
+        if not block or not st.f_blocks:
+            continue
+        used = max(0, st.f_blocks - st.f_bfree) * block
+        total = used + st.f_bavail * block
+        row = {"mount": mount, "total_mb": total // MB, "used_mb": used // MB}
+        if row["total_mb"] < MIN_DISK_MB:
+            continue
+        # points arrives sorted, so the shortest path wins the collision.
+        if (total, used) in seen:
+            continue
+        seen.add((total, used))
+        # A filesystem can refuse a write with gigabytes free once these meet.
+        if st.f_files:
+            row["inodes_total"] = st.f_files
+            row["inodes_used"] = max(0, st.f_files - st.f_ffree)
+        rows.append(row)
+        if len(rows) >= MAX_DISKS:
+            break
+    return rows
+
+
+def host_uptime(text):
+    """Seconds since boot from /proc/uptime, or None. A drop between two
+    samples is a reboot, which is worth seeing beside a latency spike."""
+    try:
+        return int(float(text.split()[0]))
+    except (IndexError, ValueError):
+        return None
+
+
+def load_average():
+    try:
+        one, five, fifteen = os.getloadavg()
+    except (OSError, AttributeError):
+        return {}
+    return {"load1": round(one, 2), "load5": round(five, 2), "load15": round(fifteen, 2)}
+
+
+def process_rss_mb(text):
+    """This package runs inside the application, so unlike the agent it can
+    honestly report the application's own memory."""
+    for line in text.splitlines():
+        if line.startswith("VmRSS:"):
+            fields = line.split()
+            if len(fields) >= 2:
+                try:
+                    return max(1, int(fields[1]) // 1024)
+                except ValueError:
+                    return None
+    return None
+
+
+class Resources:
+    """Options: server_name (the server's name as the dashboard shows it)."""
+
+    def __init__(self, core, server_name=None, **_):
+        self.core = core
+        self.server_name = str(server_name if server_name is not None else socket.gethostname())[:100]
+        import platform as _platform
+        self.runtime = "Python %s" % _platform.python_version()
+        # minute (ISO) -> row, so a minute sampled twice is kept once.
+        self.rows = {}
+        self.lock = threading.Lock()
+        self.every = EVERY
+        self.enabled = True
+        self.last_cpu = cpu_fields(read_text("/proc/stat"))
+        self.last_disk = disk_counters(read_text("/proc/diskstats"))
+        self.last_net = net_counters(read_text("/proc/net/dev"))
+        self.last_at = self._now()
+        self.sampler = Periodic(self._sample_job, SAMPLE_EVERY) if core.valid else None
+        self.job = Periodic(self._report, EVERY) if core.valid else None
+
+    @staticmethod
+    def _now():
+        return datetime.now(timezone.utc).timestamp()
+
+    def sample(self, at=None):
+        """Takes one sample, covering the time since the last one."""
+        at = self._now() if at is None else at
+        cpu = cpu_fields(read_text("/proc/stat"))
+        disk = disk_counters(read_text("/proc/diskstats"))
+        net = net_counters(read_text("/proc/net/dev"))
+        percent = cpu_percent(
+            None if self.last_cpu is None else cpu_times_of(self.last_cpu),
+            None if cpu is None else cpu_times_of(cpu),
+        )
+        elapsed = at - self.last_at
+        # The minute the interval started in, not the one it ended in.
+        minute = datetime.fromtimestamp(int(self.last_at // 60) * 60, timezone.utc)
+        row = {"minute": minute.isoformat().replace("+00:00", "Z")}
+        shares = cpu_shares(self.last_cpu, cpu)
+        rates = {}
+        if self.last_disk and disk:
+            rates["disk_read_mbs"] = rate_mbs(self.last_disk[0], disk[0], elapsed)
+            rates["disk_write_mbs"] = rate_mbs(self.last_disk[1], disk[1], elapsed)
+        if self.last_net and net:
+            rates["net_rx_mbs"] = rate_mbs(self.last_net[0], net[0], elapsed)
+            rates["net_tx_mbs"] = rate_mbs(self.last_net[1], net[1], elapsed)
+        self.last_cpu, self.last_disk, self.last_net, self.last_at = cpu, disk, net, at
+        row.update(shares)
+        row.update({name: value for name, value in rates.items() if value is not None})
+        if percent is not None and elapsed >= MIN_CPU_SECONDS:
+            row["cpu_pct"] = percent
+        cores = os.cpu_count()
+        if cores:
+            row["cpu_cores"] = cores
+        row.update(load_average())
+        row.update(memory_mb(read_text("/proc/meminfo")))
+        disks = disk_rows(mount_points(read_text("/proc/mounts")))
+        if disks:
+            row["disks"] = disks
+        rss = process_rss_mb(read_text("/proc/self/status"))
+        if rss is not None:
+            row["proc_rss_mb"] = rss
+        uptime = host_uptime(read_text("/proc/uptime"))
+        if uptime is not None:
+            row["host_uptime_s"] = uptime
+        with self.lock:
+            self.rows[row["minute"]] = row
+            # Oldest first out: a long outage keeps the recent minutes.
+            while len(self.rows) > MAX_ROWS:
+                del self.rows[min(self.rows)]
+        return row
+
+    def _sample_job(self):
+        self.sample()
+        return SAMPLE_EVERY
+
+    def flush(self):
+        """Sends what's buffered. Rows are kept only when the collector
+        couldn't take them and retrying may work."""
+        with self.lock:
+            minutes = sorted(self.rows)
+            rows = [self.rows[minute] for minute in minutes]
+        if not rows:
+            return True
+        body = {"site_id": self.core.site_id, "server_name": self.server_name,
+                "runtime": self.runtime, "rows": rows}
+        res = self.core.send("resources", "/events/resources", auth="bearer", body=body)
+        if res is None:
+            return False
+        if not getattr(res, "ok", False):
+            # Unreachable or storage down: these rows are still good. A 4xx
+            # means resending won't make them acceptable.
+            if getattr(res, "status", 0) >= 500:
+                return False
+            self._drop(minutes)
+            return True
+        try:
+            answer = res.json()
+        except Exception:
+            answer = {}
+        if isinstance(answer, dict):
+            if int(answer.get("every") or 0) > 0:
+                self.every = max(RETRY_EVERY, int(answer["every"]))
+            self.enabled = answer.get("enabled") is not False
+        self._drop(minutes)
+        return True
+
+    def _drop(self, minutes):
+        with self.lock:
+            for minute in minutes:
+                self.rows.pop(minute, None)
+
+    def _report(self):
+        if not self.core.is_on("resources"):
+            # Switched off: keep nothing, and ask again later.
+            with self.lock:
+                self.rows.clear()
+            return max(OFF_EVERY, self.every)
+        return self.every if self.flush() else RETRY_EVERY
+
+    def close(self):
+        if self.sampler:
+            self.sampler.stop()
+        if self.job:
+            self.job.stop()

analytics_platform-0.2.1.dist-info/METADATA

@@ -0,0 +1,227 @@
+Metadata-Version: 2.4
+Name: analytics-platform
+Version: 0.2.1
+Summary: Firewall, error monitoring and server analytics for your Python server, run from your analytics dashboard.
+Author: steviec87
+License-Expression: MIT
+Keywords: firewall,waf,rate-limit,error-monitoring,analytics,server-monitoring,django,flask,fastapi,wsgi,asgi
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Framework :: Django
+Classifier: Framework :: Flask
+Classifier: Framework :: FastAPI
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Internet :: Log Analysis
+Classifier: Topic :: Security
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# analytics-platform (Python)
+
+One package for your Python server, run from your analytics dashboard: a
+**firewall**, **error monitoring** and **server analytics** (payments,
+sign-ups, leads). Django, Flask, FastAPI and any WSGI or ASGI app. No
+dependencies; Python 3.8 or later.
+
+```bash
+pip install analytics-platform
+```
+
+## Django
+
+```python
+# settings.py
+MIDDLEWARE = [
+    "analytics_platform.django.PlatformMiddleware",  # first
+    # ...
+]
+
+ANALYTICS_PLATFORM = {
+    "site_id": "YOUR_SITE_ID",
+    "secret": os.environ["ANALYTICS_SITE_SECRET"],  # site settings; keep it on the server
+    "endpoint": "https://YOUR_COLLECTOR_URL",
+    # "trust_proxy": 1,             # behind Nginx or a load balancer
+    # "trust_proxy": "cloudflare",  # every request through Cloudflare
+}
+```
+
+In your code: `from analytics_platform.django import get_platform`.
+
+## FastAPI / Starlette
+
+```python
+from analytics_platform import create_platform, PlatformMiddleware
+
+platform = create_platform(site_id="YOUR_SITE_ID", secret=os.environ["ANALYTICS_SITE_SECRET"],
+                           endpoint="https://YOUR_COLLECTOR_URL")
+app.add_middleware(PlatformMiddleware, platform=platform)
+```
+
+## Flask
+
+```python
+platform = create_platform(site_id="YOUR_SITE_ID", secret=os.environ["ANALYTICS_SITE_SECRET"],
+                           endpoint="https://YOUR_COLLECTOR_URL")
+platform.init_flask(app)
+```
+
+Other WSGI apps: `app = platform.wsgi(app)`; other ASGI apps: `app = platform.asgi(app)`.
+
+## Modules
+
+| Module | What it does | Default |
+|---|---|---|
+| `firewall` | Blocks addresses, known criminal networks, shared blocks and floods (Security → Firewall) | on |
+| `firewall`'s attack patterns | Rules that match the *request* (its path, query string and user agent), not just the address, so an attack is turned away before your code runs — a package with a known hole stays safe until you update it. They come with the firewall's rules and are managed on the Security page (Firewall → Attack patterns); a pattern a real visitor might trip only watches until you promote it. Nothing to configure (protocol: `sdk/protocols/firewall.md`) | with the firewall |
+| `proxy` | Serves the tracker and takes visits under your own domain, so ad blockers can't hide those visitors | on |
+| `errors` | Sends your server's errors to the Errors report | on |
+| `analytics` | `track()`, `identify()` and `lead()` from your server | on |
+| `audit` | `platform.audit("user.role_changed", actor=..., target=..., request=...)`; Django logins and logouts on their own | on |
+| `flags` | `platform.is_enabled("new-checkout", user=user.id)`: features on or off from the dashboard | on |
+| `maintenance` | A "back soon" page while maintenance mode is on in the dashboard | on |
+| `headers` | Adds the security headers you pick on the Security page; your own headers win | on |
+| `forms` | Checks forms before you accept them: `platform.check_form(request)` | on |
+| `performance` | Response times and errors of every route (Health → Server speed): Django, Flask and FastAPI route patterns | on |
+| `crawlers` | Which search engines and AI bots fetch your pages (Health → Crawlers). Django counts them for you; elsewhere call `platform.record_crawler(...)` | on |
+| `inventory` | The installed packages and Python version, once a day, so the Security check can flag known security holes (`{"host": ...}`: the server's name) | on |
+| `posture` | How the server is set up, once a day, for the Security check: Django's `DEBUG`, `SECRET_KEY`, `ALLOWED_HOSTS` and cookie settings (when it's a Django site), whether the app runs as root, code anyone on the machine can write, and files in the folders you serve to the web that shouldn't be public (a dump, a `.env`, a `.bak`). The dashboard then asks your site for each of those files and tells you whether it really is downloadable. Reads only, and sends no file's contents. `{"roots": ["public", {"dir": "uploads", "prefix": "files"}]}` (default: Django's `STATIC_ROOT` and `MEDIA_ROOT`, reported at their `STATIC_URL` / `MEDIA_URL`), `{"checks": fn}` for checks of your own (protocol: `sdk/protocols/posture.md`) | on |
+
+Each takes `True`, `False` or its options as a dict:
+
+```python
+create_platform(site_id=..., secret=..., endpoint=...,
+                firewall={"mode": "monitor", "cache_file": "/tmp/firewall-rules.json"},
+                errors={"capture_uncaught": False},
+                analytics=False)
+```
+
+**Switch modules off in the dashboard** (Security → Settings → Server package) without a
+deploy: the package checks about once a minute. Modules are independent: one
+failing to start, or the collector being down, never stops the others, and
+never slows your requests. Background work runs in daemon threads, which start
+again in each worker after a fork (gunicorn, uWSGI).
+
+## Firewall
+
+Rules, monitor or block mode and reports are in the dashboard (Security →
+Firewall). New sites start in monitor mode.
+
+Options: `mode` (`"monitor"` or `"block"`, overrides the dashboard),
+`cache_file` (keep rules between restarts), `trust_proxy`, `counter`.
+
+**The visitor's address:** behind a proxy, every request comes from the proxy
+unless you set `trust_proxy`: `1` for one proxy or load balancer, `2` for
+Cloudflare in front of a load balancer, `"cloudflare"` when every request comes
+through Cloudflare. (Uvicorn with `--proxy-headers` already does this: leave it unset.)
+
+**Rate limit with several workers:** each worker counts on its own, so the
+limit is per worker. For one count, pass a shared counter:
+
+```python
+def counter(key, ttl):
+    hits = redis.incr(key)
+    if hits == 1:
+        redis.expire(key, ttl)
+    return hits
+
+create_platform(..., firewall={"counter": counter})
+```
+
+**Bot protection:** Django's failed logins are counted on their own; elsewhere
+call `platform.login_failed(request)` when a login fails. Past the site's limit
+the address is banned here straight away and on your other servers within a
+minute or two. Floods (over the rate limit) are banned the same way.
+
+
+**Probes.** Requests for files no visitor ever asks for (`/.env`, `/.git/…`,
+backups: the list comes with the rules) are rule `probe`; in block mode the
+address is also banned on this server, and the collector bans it on the
+site's other servers.
+## Error monitoring
+
+Uncaught exceptions are sent on their own; request errors through the
+middleware (Django, Flask, FastAPI). Errors you catch:
+
+```python
+try:
+    charge_card(order)
+except PaymentError as error:
+    platform.capture_exception(error, status=502)
+    raise
+```
+
+Options: `server_name`, `root` (traceback paths relative to it),
+`capture_uncaught`, `before_send(event, error)` (change an error, or return
+`None` to drop it).
+
+## Server analytics
+
+For what only your server knows for sure. Not pageviews: the tracker counts those.
+
+```python
+session = platform.session_id(request)  # the visit, from the X-Analytics-Session header
+
+platform.track("purchase", {"numeric_value": "49.90", "currency": "EUR", "event_uid": f"order-{order.id}"}, session_id=session)
+platform.identify(user.id, session_id=session)
+platform.lead({"email": "ana@example.com", "name": "Ana", "status": "qualified"})
+```
+
+`track()` sends in the background; `identify()` and `lead()` wait for the
+answer (up to 5 seconds).
+
+**Link to the visit:** send the tracker's session ID with your site's requests:
+
+```js
+fetch("/api/orders", { headers: { "x-analytics-session": window.analyticsSession?.getId() || "" }, ... });
+```
+
+## Ad blockers
+
+Many visitors use an ad blocker, and most blockers stop analytics. They
+recognise **the address a script comes from** and **what it is called**, so a
+tracker loaded from us is simply never counted.
+
+This package already runs on your own domain, so it serves the tracker and
+takes the visits itself. Nothing to set up: use the two addresses it gives you
+in your page's template.
+
+```python
+platform = get_platform()          # Django; elsewhere your own platform
+context = {
+    "script_url": platform.proxy.script_url(),    # /3f9a2c1b/js/v1/s.js
+    "collect_url": platform.proxy.collect_url(),  # /3f9a2c1b/api/e
+}
+```
+
+```html
+<script async src="{{ script_url }}" data-siteid="..." data-domain="example.com"
+        data-collect="{{ collect_url }}"></script>
+```
+
+- The path comes from your secret, so it isn't in the page and isn't a name
+  any blocker lists. Pick your own with `proxy={"prefix": "..."}`.
+- Tracker files are fetched once and then held in memory; if we can't be
+  reached, the copy already held is served rather than nothing.
+- The visitor's address goes on as `X-Forwarded-For` (your collector needs it
+  for the country, the daily visitor ID and the rate limit) and cookies never
+  leave your server.
+- Beacons are answered before the firewall, the crawler count and the timing,
+  so your own analytics traffic doesn't appear as pages of your site. On ASGI
+  the send runs in a thread, so the event loop keeps turning.
+- Works through the Django, WSGI (Flask, Bottle, Pyramid) and ASGI (FastAPI,
+  Starlette) middleware alike.
+- Switch it off with `proxy=False`, or in the dashboard (Site settings →
+  Server). Then load the tracker from us as before.
+
+## Shutting down and serverless
+
+`platform.flush()` sends everything waiting (on Lambda, before returning).
+`platform.close()` also stops the background threads.