analytics-platform 0.3.3__tar.gz → 0.3.4__tar.gz

{analytics_platform-0.3.3 → analytics_platform-0.3.4}/PKG-INFO

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
 Name: analytics-platform
-Version: 0.3.3
+Version: 0.3.4
 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
+Keywords: firewall,waf,rate-limit,error-monitoring,analytics,server-monitoring,django,flask,fastapi,celery,rq,dramatiq,wsgi,asgi
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: System Administrators
@@ -53,7 +53,9 @@ ANALYTICS_PLATFORM = {
 }
 ```
 
-In your code: `from analytics_platform.django import get_platform`.
+In your code: `from analytics_platform.django import get_platform`. The
+package tells the collector it is a Django site (`analytics-platform-django/…`),
+so attack patterns written for Django reach it.
 
 ## FastAPI / Starlette
 
@@ -75,6 +77,36 @@ platform.init_flask(app)
 
 Other WSGI apps: `app = platform.wsgi(app)`; other ASGI apps: `app = platform.asgi(app)`.
 
+## Celery, RQ and Dramatiq
+
+```python
+platform.init_celery(app)          # Celery: where the app is made
+platform.init_dramatiq(broker)     # Dramatiq: after dramatiq.set_broker(broker)
+PlatformWorker = platform.rq_worker()   # RQ: rq worker -w jobs.PlatformWorker
+```
+
+Every task, message or job then runs as a [job](#error-monitoring) named
+after the task, actor or function: its errors carry the route
+`/(job) shop.tasks.charge`, one that raises is sent once (status 500), and
+each run is timed (Server speed → Jobs). Prefork, solo, threads, gevent and
+eventlet pools all work (Dramatiq's `dramatiq-gevent` too), and so does
+Celery's `task_always_eager`.
+
+- A failure that will be retried is timed as failed but not sent: the error
+  is sent when the last attempt fails. Celery's `Ignore` counts as done,
+  `Reject` as failed.
+- A run cut short (`SystemExit`, a hard time limit, the worker stopping
+  mid-task) is timed as failed. Time limits are sent as errors; `SystemExit`
+  isn't.
+- A Celery or Dramatiq process killed outright (`SIGKILL`, out of memory)
+  can't be timed: nothing of the run is left to say how long it took. RQ's
+  worker outlives the process it runs a job in, so it sends and times that
+  job itself (`WorkHorseKilled`).
+- What's waiting is sent as each worker process ends. RQ runs each job in a
+  process of its own, so it sends after every job; only the worker checks
+  in (Health → All systems), not a process per job.
+- Don't also wrap a task in `platform.job()`: it would be timed twice.
+
 ## Modules
 
 | Module | What it does | Default |
@@ -89,7 +121,7 @@ Other WSGI apps: `app = platform.wsgi(app)`; other ASGI apps: `app = platform.as
 | `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 |
+| `performance` | Response times and errors of every route (Health → Server speed): Django, Flask and FastAPI route patterns, and the database queries each one ran (below) | 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 |
@@ -120,7 +152,44 @@ Options: `mode` (`"monitor"` or `"block"`, overrides the dashboard),
 **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.)
+through Cloudflare (`CF-Connecting-IP` is believed only from Cloudflare's own
+addresses: anyone who reaches your server directly can send it).
+`X-Forwarded-For` is read from the right, as each proxy appends what it saw;
+a port on an entry (`203.0.113.5:54321`, `[2001:db8::1]:443`, as Azure sends
+them) is dropped, and an entry that isn't an address (`unknown`, a name)
+means the connection's own address is used rather than no check at all.
+
+When something in front of the package already works out the address, count
+each proxy once:
+
+- **gunicorn** never changes `REMOTE_ADDR` (`--forwarded-allow-ips` is about
+  `X-Forwarded-Proto` only): set `trust_proxy`.
+- **Uvicorn** (`--proxy-headers`, on by default, trusting the addresses in
+  `--forwarded-allow-ips`) puts the visitor's address in place itself, and
+  leaves the header as it was. Leave `trust_proxy` unset when
+  `--forwarded-allow-ips` lists your proxies' addresses. With
+  `--forwarded-allow-ips='*'` (`FORWARDED_ALLOW_IPS=*`, common in Docker images)
+  Uvicorn takes the **leftmost** entry, which the visitor writes: there, set
+  `trust_proxy` to your number of proxies, and the package reads the header
+  itself from the right.
+- **werkzeug's `ProxyFix`**: wrapped inside the package's middleware
+  (`app.wsgi_app = ProxyFix(app.wsgi_app, x_for=1)` before `init_flask`), the
+  package uses its `x_for` when `trust_proxy` is unset; wrapped outside, it has
+  already set `REMOTE_ADDR` and unset `trust_proxy` uses that.
+- **Apache's `mod_remoteip`** (`mod_wsgi`) sets `REMOTE_ADDR` to the visitor
+  and *removes the entries it used* from `X-Forwarded-For`, leaving only what
+  the visitor wrote. Leave `trust_proxy` unset there: counting the same proxy
+  again would believe the visitor's own entry.
+- **Django** reads no forwarding header of its own: as gunicorn or Uvicorn
+  above, whichever runs it.
+
+**What the rate limit counts:** requests per IPv4 address, or per IPv6
+**/64** (one machine usually holds a whole /64, so counting addresses would let
+it start afresh on every request); `::ffff:a.b.c.d` counts as `a.b.c.d`. The
+same goes for bans and failed logins. Static files (`.css`, `.js`, images,
+fonts, video, `.pdf`, `.wasm`, and anything under `/static/`) aren't counted,
+so a page with 40 assets is one hit, not 41. A full table of counts (100,000)
+drops its oldest entries, never everyone's.
 
 **Rate limit with several workers:** each worker counts on its own, so the
 limit is per worker. For one count, pass a shared counter:
@@ -145,6 +214,22 @@ minute or two. Floods (over the rate limit) are banned the same way.
 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.
+
+**Browser check** (paid plans, switched on in the dashboard). A visitor's
+first page of the day is a short "checking your browser" page that sets a
+cookie with JavaScript and reloads; after that the site answers as usual for
+about a day. Only a `GET` or `HEAD` that asks for a web page is checked: forms,
+webhooks, payment callbacks, API calls (`Accept: application/json`), the paths
+you exclude (`/api/`, …), your allowed addresses, search engines and the AI
+crawlers that bring visits never see it. It stops cheap floods — scripts that
+don't run JavaScript — and nothing more: a real browser, or a bot driving one,
+gets through. It's a speed bump against scripts that don't run JavaScript: a
+bot written for this product can read the pass from the page, which is why
+the pass is bound to the visitor's address and the day. The cookie, `__sg_pass`, holds a signed day and nothing about the
+visitor; it exists only to keep the site reachable, so it is strictly necessary
+and needs no consent. Checked requests show on the Security page as rule
+`challenge`.
+
 ## Error monitoring
 
 Uncaught exceptions are sent on their own; request errors through the
@@ -163,7 +248,10 @@ 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.
+a few seconds later. A visitor who hangs up mid-request (`BrokenPipeError`,
+`ConnectionResetError`, Starlette's `ClientDisconnect`, Django's
+`UnreadablePostError`) isn't sent as a server error. Messages are cut at
+2,000 characters; the traceback keeps the detail.
 
 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.
@@ -202,6 +290,27 @@ Options: `server_name`, `root` (traceback paths relative to it),
 `False` for none), `before_send(event, error)` (change an error, or return
 `None` to drop it).
 
+## Database queries
+
+Server speed also shows which queries a route spends its time on (Health →
+Server speed → Queries): per route and query, how many ran, how many failed and
+how long they took. Every value is taken out of a query on your server before
+it is counted (`WHERE email = ?`, `IN (?)`), and bound parameters are never
+read, so no data leaves it.
+
+| Library | Setup |
+|---|---|
+| Django | nothing: every connection, under the request or job that ran the query |
+| SQLAlchemy | nothing: every engine (Flask-SQLAlchemy too) |
+| pymongo | nothing, but **create the platform before your `MongoClient`**: pymongo only reports to clients made after the package is listening |
+| Any other DB-API driver (psycopg, psycopg2, mysqlclient, PyMySQL, sqlite3...) | `conn = platform.watch_database(psycopg.connect(...))`, and use `conn` as before |
+
+A query outside any request or job is counted as `JOB (background)`. Each
+query is counted once: when SQLAlchemy or Django runs it over a watched
+connection, they count it and the connection doesn't. It is on with
+`performance`, and switched off with it in the dashboard; `queries=False`
+keeps Server speed and leaves queries out (protocol: `sdk/protocols/queries.md`).
+
 ## Server analytics
 
 For what only your server knows for sure. Not pageviews: the tracker counts those.
@@ -215,7 +324,10 @@ 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).
+answer (up to 5 seconds). What you pass is taken as JSON when you pass it
+(also `audit()`'s `details`): a date becomes ISO text, a `Decimal` a number,
+a set a list, `NaN` null and anything else its `str()`, so one odd value can't
+fail the batch it is sent in.
 
 **Link to the visit:** send the tracker's session ID with your site's requests:
 
@@ -258,6 +370,12 @@ context = {
   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.
+- A denied or banned address (and one in the blocklists or shared blocks)
+  gets nothing from it either; beacons are never rate-limited or checked.
+- It runs on your request threads, so it never waits long: 2 seconds at most,
+  and after 3 failures in a row the collector is left alone for 30 seconds
+  (beacons are answered `502` at once, which the tracker treats as lost, and a
+  tracker file that couldn't be fetched isn't asked for again for 30 seconds).
 - Switch it off with `proxy=False`, or in the dashboard (Site settings →
   Server). Then load the tracker from us as before.
 
@@ -265,3 +383,12 @@ context = {
 
 `platform.flush()` sends everything waiting (on Lambda, before returning).
 `platform.close()` also stops the background threads.
+
+When the process ends (and when a Celery, RQ or Dramatiq worker shuts down),
+what's waiting is sent within **5 seconds** for every module together, so the
+package never outlasts a container's or PM2's 30-second grace period: no retry
+sleeps then, and the errors that weren't sent wait in the errors file for the
+next start. `platform.flush_before_exit()` does the same from your own
+shutdown hook. The errors file a resend takes is deleted only once it has
+been sent, so a process killed meanwhile loses nothing (the next start takes
+over a file left behind for 5 minutes).

{analytics_platform-0.3.3 → analytics_platform-0.3.4}/README.md

@@ -27,7 +27,9 @@ ANALYTICS_PLATFORM = {
 }
 ```
 
-In your code: `from analytics_platform.django import get_platform`.
+In your code: `from analytics_platform.django import get_platform`. The
+package tells the collector it is a Django site (`analytics-platform-django/…`),
+so attack patterns written for Django reach it.
 
 ## FastAPI / Starlette
 
@@ -49,6 +51,36 @@ platform.init_flask(app)
 
 Other WSGI apps: `app = platform.wsgi(app)`; other ASGI apps: `app = platform.asgi(app)`.
 
+## Celery, RQ and Dramatiq
+
+```python
+platform.init_celery(app)          # Celery: where the app is made
+platform.init_dramatiq(broker)     # Dramatiq: after dramatiq.set_broker(broker)
+PlatformWorker = platform.rq_worker()   # RQ: rq worker -w jobs.PlatformWorker
+```
+
+Every task, message or job then runs as a [job](#error-monitoring) named
+after the task, actor or function: its errors carry the route
+`/(job) shop.tasks.charge`, one that raises is sent once (status 500), and
+each run is timed (Server speed → Jobs). Prefork, solo, threads, gevent and
+eventlet pools all work (Dramatiq's `dramatiq-gevent` too), and so does
+Celery's `task_always_eager`.
+
+- A failure that will be retried is timed as failed but not sent: the error
+  is sent when the last attempt fails. Celery's `Ignore` counts as done,
+  `Reject` as failed.
+- A run cut short (`SystemExit`, a hard time limit, the worker stopping
+  mid-task) is timed as failed. Time limits are sent as errors; `SystemExit`
+  isn't.
+- A Celery or Dramatiq process killed outright (`SIGKILL`, out of memory)
+  can't be timed: nothing of the run is left to say how long it took. RQ's
+  worker outlives the process it runs a job in, so it sends and times that
+  job itself (`WorkHorseKilled`).
+- What's waiting is sent as each worker process ends. RQ runs each job in a
+  process of its own, so it sends after every job; only the worker checks
+  in (Health → All systems), not a process per job.
+- Don't also wrap a task in `platform.job()`: it would be timed twice.
+
 ## Modules
 
 | Module | What it does | Default |
@@ -63,7 +95,7 @@ Other WSGI apps: `app = platform.wsgi(app)`; other ASGI apps: `app = platform.as
 | `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 |
+| `performance` | Response times and errors of every route (Health → Server speed): Django, Flask and FastAPI route patterns, and the database queries each one ran (below) | 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 |
@@ -94,7 +126,44 @@ Options: `mode` (`"monitor"` or `"block"`, overrides the dashboard),
 **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.)
+through Cloudflare (`CF-Connecting-IP` is believed only from Cloudflare's own
+addresses: anyone who reaches your server directly can send it).
+`X-Forwarded-For` is read from the right, as each proxy appends what it saw;
+a port on an entry (`203.0.113.5:54321`, `[2001:db8::1]:443`, as Azure sends
+them) is dropped, and an entry that isn't an address (`unknown`, a name)
+means the connection's own address is used rather than no check at all.
+
+When something in front of the package already works out the address, count
+each proxy once:
+
+- **gunicorn** never changes `REMOTE_ADDR` (`--forwarded-allow-ips` is about
+  `X-Forwarded-Proto` only): set `trust_proxy`.
+- **Uvicorn** (`--proxy-headers`, on by default, trusting the addresses in
+  `--forwarded-allow-ips`) puts the visitor's address in place itself, and
+  leaves the header as it was. Leave `trust_proxy` unset when
+  `--forwarded-allow-ips` lists your proxies' addresses. With
+  `--forwarded-allow-ips='*'` (`FORWARDED_ALLOW_IPS=*`, common in Docker images)
+  Uvicorn takes the **leftmost** entry, which the visitor writes: there, set
+  `trust_proxy` to your number of proxies, and the package reads the header
+  itself from the right.
+- **werkzeug's `ProxyFix`**: wrapped inside the package's middleware
+  (`app.wsgi_app = ProxyFix(app.wsgi_app, x_for=1)` before `init_flask`), the
+  package uses its `x_for` when `trust_proxy` is unset; wrapped outside, it has
+  already set `REMOTE_ADDR` and unset `trust_proxy` uses that.
+- **Apache's `mod_remoteip`** (`mod_wsgi`) sets `REMOTE_ADDR` to the visitor
+  and *removes the entries it used* from `X-Forwarded-For`, leaving only what
+  the visitor wrote. Leave `trust_proxy` unset there: counting the same proxy
+  again would believe the visitor's own entry.
+- **Django** reads no forwarding header of its own: as gunicorn or Uvicorn
+  above, whichever runs it.
+
+**What the rate limit counts:** requests per IPv4 address, or per IPv6
+**/64** (one machine usually holds a whole /64, so counting addresses would let
+it start afresh on every request); `::ffff:a.b.c.d` counts as `a.b.c.d`. The
+same goes for bans and failed logins. Static files (`.css`, `.js`, images,
+fonts, video, `.pdf`, `.wasm`, and anything under `/static/`) aren't counted,
+so a page with 40 assets is one hit, not 41. A full table of counts (100,000)
+drops its oldest entries, never everyone's.
 
 **Rate limit with several workers:** each worker counts on its own, so the
 limit is per worker. For one count, pass a shared counter:
@@ -119,6 +188,22 @@ minute or two. Floods (over the rate limit) are banned the same way.
 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.
+
+**Browser check** (paid plans, switched on in the dashboard). A visitor's
+first page of the day is a short "checking your browser" page that sets a
+cookie with JavaScript and reloads; after that the site answers as usual for
+about a day. Only a `GET` or `HEAD` that asks for a web page is checked: forms,
+webhooks, payment callbacks, API calls (`Accept: application/json`), the paths
+you exclude (`/api/`, …), your allowed addresses, search engines and the AI
+crawlers that bring visits never see it. It stops cheap floods — scripts that
+don't run JavaScript — and nothing more: a real browser, or a bot driving one,
+gets through. It's a speed bump against scripts that don't run JavaScript: a
+bot written for this product can read the pass from the page, which is why
+the pass is bound to the visitor's address and the day. The cookie, `__sg_pass`, holds a signed day and nothing about the
+visitor; it exists only to keep the site reachable, so it is strictly necessary
+and needs no consent. Checked requests show on the Security page as rule
+`challenge`.
+
 ## Error monitoring
 
 Uncaught exceptions are sent on their own; request errors through the
@@ -137,7 +222,10 @@ 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.
+a few seconds later. A visitor who hangs up mid-request (`BrokenPipeError`,
+`ConnectionResetError`, Starlette's `ClientDisconnect`, Django's
+`UnreadablePostError`) isn't sent as a server error. Messages are cut at
+2,000 characters; the traceback keeps the detail.
 
 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.
@@ -176,6 +264,27 @@ Options: `server_name`, `root` (traceback paths relative to it),
 `False` for none), `before_send(event, error)` (change an error, or return
 `None` to drop it).
 
+## Database queries
+
+Server speed also shows which queries a route spends its time on (Health →
+Server speed → Queries): per route and query, how many ran, how many failed and
+how long they took. Every value is taken out of a query on your server before
+it is counted (`WHERE email = ?`, `IN (?)`), and bound parameters are never
+read, so no data leaves it.
+
+| Library | Setup |
+|---|---|
+| Django | nothing: every connection, under the request or job that ran the query |
+| SQLAlchemy | nothing: every engine (Flask-SQLAlchemy too) |
+| pymongo | nothing, but **create the platform before your `MongoClient`**: pymongo only reports to clients made after the package is listening |
+| Any other DB-API driver (psycopg, psycopg2, mysqlclient, PyMySQL, sqlite3...) | `conn = platform.watch_database(psycopg.connect(...))`, and use `conn` as before |
+
+A query outside any request or job is counted as `JOB (background)`. Each
+query is counted once: when SQLAlchemy or Django runs it over a watched
+connection, they count it and the connection doesn't. It is on with
+`performance`, and switched off with it in the dashboard; `queries=False`
+keeps Server speed and leaves queries out (protocol: `sdk/protocols/queries.md`).
+
 ## Server analytics
 
 For what only your server knows for sure. Not pageviews: the tracker counts those.
@@ -189,7 +298,10 @@ 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).
+answer (up to 5 seconds). What you pass is taken as JSON when you pass it
+(also `audit()`'s `details`): a date becomes ISO text, a `Decimal` a number,
+a set a list, `NaN` null and anything else its `str()`, so one odd value can't
+fail the batch it is sent in.
 
 **Link to the visit:** send the tracker's session ID with your site's requests:
 
@@ -232,6 +344,12 @@ context = {
   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.
+- A denied or banned address (and one in the blocklists or shared blocks)
+  gets nothing from it either; beacons are never rate-limited or checked.
+- It runs on your request threads, so it never waits long: 2 seconds at most,
+  and after 3 failures in a row the collector is left alone for 30 seconds
+  (beacons are answered `502` at once, which the tracker treats as lost, and a
+  tracker file that couldn't be fetched isn't asked for again for 30 seconds).
 - Switch it off with `proxy=False`, or in the dashboard (Site settings →
   Server). Then load the tracker from us as before.
 
@@ -239,3 +357,12 @@ context = {
 
 `platform.flush()` sends everything waiting (on Lambda, before returning).
 `platform.close()` also stops the background threads.
+
+When the process ends (and when a Celery, RQ or Dramatiq worker shuts down),
+what's waiting is sent within **5 seconds** for every module together, so the
+package never outlasts a container's or PM2's 30-second grace period: no retry
+sleeps then, and the errors that weren't sent wait in the errors file for the
+next start. `platform.flush_before_exit()` does the same from your own
+shutdown hook. The errors file a resend takes is deleted only once it has
+been sent, so a process killed meanwhile loses nothing (the next start takes
+over a file left behind for 5 minutes).