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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: analytics-platform
-Version: 0.3.4
+Version: 0.3.6
 Summary: Firewall, error monitoring and server analytics for your Python server, run from your analytics dashboard.
 Author: steviec87
 License-Expression: MIT
@@ -106,6 +106,7 @@ Celery's `task_always_eager`.
   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.
+- Each queue's backlog: [`platform.watch_queue(...)`](#job-queues).
 
 ## Modules
 
@@ -121,8 +122,8 @@ Celery's `task_always_eager`.
 | `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, 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 |
+| `performance` | Response times and errors of every route (Health → Server speed): Django, Flask and FastAPI route patterns, the database queries each one ran, the other services it waited on, and your job queues' backlog (below) | on |
+| `crawlers` | Which search engines and AI bots fetch your pages (Off-site → 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 |
 
@@ -275,15 +276,26 @@ 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, and Health → All systems lists
+Health → Updates then tell the apps apart, and Health → All systems lists
 each with a light: the package checks in about once a minute, so an app that
 stops reads "Stopped" within ten minutes (`sdk/protocols/checkin.md`).
 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.
+your own apps, so the rate limit would see one visitor).
+
+**Several apps on one machine**: leave `resources` on in all of them. The
+machine's CPU, memory and disks are shown once, and each app (each gunicorn
+or Celery worker process too) adds what is its own: its container's memory
+and CPU caps and how close it is to them, how often the cap throttled it,
+processes the kernel killed for memory, open files against the limit, the
+most requests in progress at once, and how long it has run. On Linux the
+machine's waiting time (`/proc/pressure`), connections refused before the
+app accepted them and the connection-tracking table come with them. Python
+sends no heap or garbage-collection figures. A figure the machine won't give
+(no cap, no PSI, not Linux) is left out, never sent as 0 (protocol:
+`sdk/protocols/resources.md`, "Limits").
 
 Options: `server_name`, `root` (traceback paths relative to it),
 `capture_uncaught`, `capture_logging`, `spool_dir` (where unsent errors wait;
@@ -304,6 +316,9 @@ read, so no data leaves it.
 | 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 |
+| ClickHouse: clickhouse-connect, clickhouse-driver | `client = platform.watch_database(clickhouse_connect.get_client(...))` (or a `clickhouse_driver.Client`), and use `client` as before |
+| Redis: redis-py (`Redis`, `RedisCluster`, sync or `redis.asyncio`) | `platform.watch_database(r)`: the client is watched in place, so keep using `r` |
+| Django's cache on Redis (Django's own `RedisCache`, or django-redis) | `platform.watch_database(caches["default"])`, once at start-up (in `AppConfig.ready()`) |
 
 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
@@ -311,6 +326,95 @@ 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`).
 
+ClickHouse: clickhouse-connect's `query()` (and `query_df()`, `query_np()`,
+`query_arrow()`, `raw_query()`) reads the whole result before it returns, so
+its time is the result's too; `command()` and the inserts are timed until
+they answer. clickhouse-driver's `execute()` likewise. The streaming
+queries (`query_rows_stream()`, `execute_iter()`) aren't timed. Only the
+client you pass is wrapped; the library itself is left alone.
+
+Redis: each command is counted by its name and the shape of its key (`GET
+user:?:cart`); no other argument or value is read. A pipeline or transaction
+is one call (`PIPELINE GET user:?`, `MULTI SET cart:?`), timed as a whole.
+Commands that wait (`BLPOP`, `XREAD BLOCK`, subscribing) aren't timed, and
+nor are this package's own reads of your RQ queues. An error reply counts
+as failed; a nil reply doesn't.
+
+```python
+r = redis.Redis.from_url(REDIS_URL)
+platform.watch_database(r)
+
+# Django (settings: CACHES backend django.core.cache.backends.redis.RedisCache
+# or django_redis.cache.RedisCache), in your AppConfig.ready():
+from django.core.cache import caches
+platform.watch_database(caches["default"])
+```
+
+## Outgoing calls
+
+Health → Server speed → Calls shows how long each route waited on other
+services (a payment provider, an email API, your own microservices) by the
+host it called (`api.stripe.com`), with how many calls failed. One line for
+each client, where you make it:
+
+```python
+session = platform.watch_http(requests.Session())     # requests
+client = platform.watch_http(httpx.Client())          # httpx; AsyncClient too
+
+# httpx, with calls that got no answer counted too:
+client = httpx.Client(transport=platform.watch_http(httpx.HTTPTransport()))
+```
+
+- **Only the host is sent.** A call's path, query string, headers and body
+  never leave your server: paths carry IDs and keys.
+- A call is timed from being sent to its response's headers arriving. A
+  call that got no answer (refused, timed out), or a 5xx, is a failed one; a
+  4xx is the other side's answer, not a failure. A call your code cancels
+  isn't counted.
+- requests: each adapter the session has mounted is wrapped, keeping its
+  retries and pool settings; mount your own adapters before watching.
+- httpx: `watch_http(client)` adds event hooks, which see every answered
+  call but not one that got no answer at all. A watched transport
+  (`AsyncHTTPTransport` for an `AsyncClient`) sees those too; with both on
+  one client a call is counted once.
+- urllib3 and `urllib.request` have no public hook, so their calls aren't
+  counted (and nothing of theirs is patched).
+- Calls are filed as queries are: under the request, the job, or
+  `JOB (background)`. The package's own calls to us are left out.
+- They ride on Server speed's switch; `calls=False` leaves them out
+  (protocol: `sdk/protocols/calls.md`).
+
+## Job queues
+
+Health → Server speed → Jobs shows each queue's backlog once a minute: jobs
+waiting, running, delayed and failed, how long the oldest has waited, and
+jobs added against jobs finished, so a queue falling behind shows before the
+emails go out an hour late.
+
+```python
+platform.watch_queue(celery_app)                 # Celery on a Redis broker; queues=["emails", ...] to name them
+platform.watch_queue(Queue("emails", connection=redis))   # RQ, in web servers and workers alike
+```
+
+- **Celery** has no backlog API, so the broker's own lists are read from
+  Redis (one `LLEN` per queue and priority). Celery can't say what is
+  running, delayed or failed, nor how long a message has waited, so those
+  are left out; each process counts the tasks it published and, in a
+  worker, the ones it finished (a retry isn't finished). With a RabbitMQ
+  broker nothing is sent from here: the server agent reads RabbitMQ's own
+  numbers.
+- **RQ**: the queue, its started, scheduled, deferred and failed job
+  registries, and when its first job was added. RQ has no hook for a job
+  being added; jobs finished are counted by `platform.rq_worker()`'s
+  worker, so watch the queue in the worker's code too.
+- Watching one queue in several processes is fine: the dashboard takes the
+  largest reading, never the sum. Its Redis is named by host, port and
+  database; never a password.
+- A reading that fails is a gap, not a zero. Readings run on a background
+  thread, never in a request.
+- They ride on Server speed's switch; `queues=False` leaves them out
+  (protocol: `sdk/protocols/queues.md`).
+
 ## Server analytics
 
 For what only your server knows for sure. Not pageviews: the tracker counts those.

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

@@ -80,6 +80,7 @@ Celery's `task_always_eager`.
   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.
+- Each queue's backlog: [`platform.watch_queue(...)`](#job-queues).
 
 ## Modules
 
@@ -95,8 +96,8 @@ Celery's `task_always_eager`.
 | `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, 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 |
+| `performance` | Response times and errors of every route (Health → Server speed): Django, Flask and FastAPI route patterns, the database queries each one ran, the other services it waited on, and your job queues' backlog (below) | on |
+| `crawlers` | Which search engines and AI bots fetch your pages (Off-site → 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 |
 
@@ -249,15 +250,26 @@ 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, and Health → All systems lists
+Health → Updates then tell the apps apart, and Health → All systems lists
 each with a light: the package checks in about once a minute, so an app that
 stops reads "Stopped" within ten minutes (`sdk/protocols/checkin.md`).
 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.
+your own apps, so the rate limit would see one visitor).
+
+**Several apps on one machine**: leave `resources` on in all of them. The
+machine's CPU, memory and disks are shown once, and each app (each gunicorn
+or Celery worker process too) adds what is its own: its container's memory
+and CPU caps and how close it is to them, how often the cap throttled it,
+processes the kernel killed for memory, open files against the limit, the
+most requests in progress at once, and how long it has run. On Linux the
+machine's waiting time (`/proc/pressure`), connections refused before the
+app accepted them and the connection-tracking table come with them. Python
+sends no heap or garbage-collection figures. A figure the machine won't give
+(no cap, no PSI, not Linux) is left out, never sent as 0 (protocol:
+`sdk/protocols/resources.md`, "Limits").
 
 Options: `server_name`, `root` (traceback paths relative to it),
 `capture_uncaught`, `capture_logging`, `spool_dir` (where unsent errors wait;
@@ -278,6 +290,9 @@ read, so no data leaves it.
 | 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 |
+| ClickHouse: clickhouse-connect, clickhouse-driver | `client = platform.watch_database(clickhouse_connect.get_client(...))` (or a `clickhouse_driver.Client`), and use `client` as before |
+| Redis: redis-py (`Redis`, `RedisCluster`, sync or `redis.asyncio`) | `platform.watch_database(r)`: the client is watched in place, so keep using `r` |
+| Django's cache on Redis (Django's own `RedisCache`, or django-redis) | `platform.watch_database(caches["default"])`, once at start-up (in `AppConfig.ready()`) |
 
 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
@@ -285,6 +300,95 @@ 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`).
 
+ClickHouse: clickhouse-connect's `query()` (and `query_df()`, `query_np()`,
+`query_arrow()`, `raw_query()`) reads the whole result before it returns, so
+its time is the result's too; `command()` and the inserts are timed until
+they answer. clickhouse-driver's `execute()` likewise. The streaming
+queries (`query_rows_stream()`, `execute_iter()`) aren't timed. Only the
+client you pass is wrapped; the library itself is left alone.
+
+Redis: each command is counted by its name and the shape of its key (`GET
+user:?:cart`); no other argument or value is read. A pipeline or transaction
+is one call (`PIPELINE GET user:?`, `MULTI SET cart:?`), timed as a whole.
+Commands that wait (`BLPOP`, `XREAD BLOCK`, subscribing) aren't timed, and
+nor are this package's own reads of your RQ queues. An error reply counts
+as failed; a nil reply doesn't.
+
+```python
+r = redis.Redis.from_url(REDIS_URL)
+platform.watch_database(r)
+
+# Django (settings: CACHES backend django.core.cache.backends.redis.RedisCache
+# or django_redis.cache.RedisCache), in your AppConfig.ready():
+from django.core.cache import caches
+platform.watch_database(caches["default"])
+```
+
+## Outgoing calls
+
+Health → Server speed → Calls shows how long each route waited on other
+services (a payment provider, an email API, your own microservices) by the
+host it called (`api.stripe.com`), with how many calls failed. One line for
+each client, where you make it:
+
+```python
+session = platform.watch_http(requests.Session())     # requests
+client = platform.watch_http(httpx.Client())          # httpx; AsyncClient too
+
+# httpx, with calls that got no answer counted too:
+client = httpx.Client(transport=platform.watch_http(httpx.HTTPTransport()))
+```
+
+- **Only the host is sent.** A call's path, query string, headers and body
+  never leave your server: paths carry IDs and keys.
+- A call is timed from being sent to its response's headers arriving. A
+  call that got no answer (refused, timed out), or a 5xx, is a failed one; a
+  4xx is the other side's answer, not a failure. A call your code cancels
+  isn't counted.
+- requests: each adapter the session has mounted is wrapped, keeping its
+  retries and pool settings; mount your own adapters before watching.
+- httpx: `watch_http(client)` adds event hooks, which see every answered
+  call but not one that got no answer at all. A watched transport
+  (`AsyncHTTPTransport` for an `AsyncClient`) sees those too; with both on
+  one client a call is counted once.
+- urllib3 and `urllib.request` have no public hook, so their calls aren't
+  counted (and nothing of theirs is patched).
+- Calls are filed as queries are: under the request, the job, or
+  `JOB (background)`. The package's own calls to us are left out.
+- They ride on Server speed's switch; `calls=False` leaves them out
+  (protocol: `sdk/protocols/calls.md`).
+
+## Job queues
+
+Health → Server speed → Jobs shows each queue's backlog once a minute: jobs
+waiting, running, delayed and failed, how long the oldest has waited, and
+jobs added against jobs finished, so a queue falling behind shows before the
+emails go out an hour late.
+
+```python
+platform.watch_queue(celery_app)                 # Celery on a Redis broker; queues=["emails", ...] to name them
+platform.watch_queue(Queue("emails", connection=redis))   # RQ, in web servers and workers alike
+```
+
+- **Celery** has no backlog API, so the broker's own lists are read from
+  Redis (one `LLEN` per queue and priority). Celery can't say what is
+  running, delayed or failed, nor how long a message has waited, so those
+  are left out; each process counts the tasks it published and, in a
+  worker, the ones it finished (a retry isn't finished). With a RabbitMQ
+  broker nothing is sent from here: the server agent reads RabbitMQ's own
+  numbers.
+- **RQ**: the queue, its started, scheduled, deferred and failed job
+  registries, and when its first job was added. RQ has no hook for a job
+  being added; jobs finished are counted by `platform.rq_worker()`'s
+  worker, so watch the queue in the worker's code too.
+- Watching one queue in several processes is fine: the dashboard takes the
+  largest reading, never the sum. Its Redis is named by host, port and
+  database; never a password.
+- A reading that fails is a gap, not a zero. Readings run on a background
+  thread, never in a request.
+- They ride on Server speed's switch; `queues=False` leaves them out
+  (protocol: `sdk/protocols/queues.md`).
+
 ## Server analytics
 
 For what only your server knows for sure. Not pageviews: the tracker counts those.