analytics-platform 0.3.5__tar.gz → 0.3.7__tar.gz

{analytics_platform-0.3.5 → analytics_platform-0.3.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: analytics-platform
-Version: 0.3.5
+Version: 0.3.7
 Summary: Firewall, error monitoring and server analytics for your Python server, run from your analytics dashboard.
 Author: steviec87
 License-Expression: MIT
@@ -317,6 +317,8 @@ read, so no data leaves it.
 | 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
@@ -331,6 +333,23 @@ 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
@@ -404,7 +423,7 @@ For what only your server knows for sure. Not pageviews: the tracker counts thos
 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.identify(user.id, session_id=session, traits={"plan": "pro", "seats": 5, "trial": False})  # traits are optional
 platform.lead({"email": "ana@example.com", "name": "Ana", "status": "qualified"})
 ```
 
@@ -414,6 +433,13 @@ answer (up to 5 seconds). What you pass is taken as JSON when you pass it
 a set a list, `NaN` null and anything else its `str()`, so one odd value can't
 fail the batch it is sent in.
 
+**User traits:** `identify()` takes optional `traits`, a dict of name to
+text, number or `True`/`False`. Lists, dicts and other values are left out
+(and `traits` is left off when nothing is left). The collector does the rest:
+names are lowercased with spaces and dashes as `_` (up to 40 letters, digits
+and `_`), text is cut at 200 characters, values that look like an email
+address are dropped, and at most 20 are kept.
+
 **Link to the visit:** send the tracker's session ID with your site's requests:
 
 ```js

{analytics_platform-0.3.5 → analytics_platform-0.3.7}/README.md

@@ -291,6 +291,8 @@ read, so no data leaves it.
 | 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
@@ -305,6 +307,23 @@ 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
@@ -378,7 +397,7 @@ For what only your server knows for sure. Not pageviews: the tracker counts thos
 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.identify(user.id, session_id=session, traits={"plan": "pro", "seats": 5, "trial": False})  # traits are optional
 platform.lead({"email": "ana@example.com", "name": "Ana", "status": "qualified"})
 ```
 
@@ -388,6 +407,13 @@ answer (up to 5 seconds). What you pass is taken as JSON when you pass it
 a set a list, `NaN` null and anything else its `str()`, so one odd value can't
 fail the batch it is sent in.
 
+**User traits:** `identify()` takes optional `traits`, a dict of name to
+text, number or `True`/`False`. Lists, dicts and other values are left out
+(and `traits` is left off when nothing is left). The collector does the rest:
+names are lowercased with spaces and dashes as `_` (up to 40 letters, digits
+and `_`), text is cut at 200 characters, values that look like an email
+address are dropped, and at most 20 are kept.
+
 **Link to the visit:** send the tracker's session ID with your site's requests:
 
 ```js

{analytics_platform-0.3.5 → analytics_platform-0.3.7}/analytics_platform/__init__.py

@@ -308,9 +308,9 @@ class Platform:
         analytics = self._modules.get("analytics")
         return analytics.track(name, fields, session_id) if analytics else ""
 
-    def identify(self, user_id, session_id=""):
+    def identify(self, user_id, session_id="", traits=None):
         analytics = self._modules.get("analytics")
-        return analytics.identify(user_id, session_id) if analytics else False
+        return analytics.identify(user_id, session_id, traits) if analytics else False
 
     def lead(self, fields, session_id=""):
         analytics = self._modules.get("analytics")
@@ -342,12 +342,18 @@ class Platform:
         sqlite3...) or a ClickHouse client (clickhouse-connect,
         clickhouse-driver) whose queries are timed for Server speed: use what
         it returns in its place. db: "postgresql", "mysql"... when the driver
-        doesn't say. Django, SQLAlchemy and pymongo need nothing of this."""
+        doesn't say. Django, SQLAlchemy and pymongo need nothing of this.
+        A redis-py client (Redis, RedisCluster, sync or asyncio) or a Django
+        cache on Redis is watched in place and handed back as itself."""
         queries = self._queries()
         if queries is None:
             return connection
         from .queries import watch_database
-        return watch_database(connection, db)
+        try:
+            return watch_database(connection, db)
+        except Exception as error:
+            self.core.log("performance", "watch_database: its queries aren't timed:", error)
+            return connection
 
     def watch_http(self, client):
         """A requests Session, an httpx Client or AsyncClient, or an httpx

{analytics_platform-0.3.5 → analytics_platform-0.3.7}/analytics_platform/analytics.py

@@ -4,13 +4,15 @@ tracker counts those, and counting them here too would count them twice.
 
 - track(): events, batched to POST /events/server-events in the background.
   Each gets an event_uid, so a retried batch can be told apart from new events.
-- identify(): links the browser's visit to your user ID (/events/identify).
+- identify(): links the browser's visit to your user ID (/events/identify),
+  with optional traits about the user (plan, seats...).
 - lead(): adds or updates a lead (/events/lead).
 identify() and lead() wait for the answer (up to 5 seconds).
 Pass session_id to link an event to the visit: the page sends
 window.analyticsSession.getId() in the X-Analytics-Session header, and the
 framework integrations give you platform.session_id(request).
 """
+import math
 import threading
 import uuid
 from datetime import datetime, timezone
@@ -23,6 +25,16 @@ FLUSH_EVERY = 2
 RETRY = 15
 
 
+def scalar_traits(traits):
+    """The traits that are text, a finite number or True/False; {} when none is."""
+    if not isinstance(traits, dict):
+        return {}
+    return {
+        str(name): value for name, value in traits.items()
+        if isinstance(value, (str, bool, int)) or (isinstance(value, float) and math.isfinite(value))
+    }
+
+
 class Analytics:
     def __init__(self, core, **_):
         self.core = core
@@ -79,11 +91,18 @@ class Analytics:
     def _flush_job(self):
         return FLUSH_EVERY if self.flush() else RETRY
 
-    def identify(self, user_id, session_id=""):
-        """Links the visit to your user ID. True when stored."""
+    def identify(self, user_id, session_id="", traits=None):
+        """Links the visit to your user ID. True when stored. traits: what you
+        know about the user, name -> text, number or True/False
+        ({"plan": "pro", "seats": 5}); anything else is left out, and the
+        collector cleans the names and values."""
         if not user_id or not session_id or not self.core.is_on("analytics"):
             return False
-        res = self.core.send("analytics", "/events/identify", body={"user_id": str(user_id), "session_id": session_id})
+        body = {"user_id": str(user_id), "session_id": session_id}
+        kept = scalar_traits(traits)
+        if kept:
+            body["traits"] = kept
+        res = self.core.send("analytics", "/events/identify", body=body)
         return bool(res and res.ok)
 
     def lead(self, fields, session_id=""):

{analytics_platform-0.3.5 → analytics_platform-0.3.7}/analytics_platform/core.py

@@ -23,7 +23,7 @@ import urllib.error
 import urllib.parse
 import urllib.request
 
-VERSION = "0.3.5"
+VERSION = "0.3.7"
 TIMEOUT = 5
 MIN_SYNC = 30
 RETRY = 60