docs: Work on POLL_STATS docs

Author: defnull

docs/accounting.rst

@@ -46,28 +46,35 @@ Enabling `POLL_STATS`
    This is an experimental feature.
 
 
-BBBLB can store meeting statistics (namely `users`, `voice` and `video` counts) into the
-database, allowing you to run your own queries and analytics. This is disabled by default,
-because one database row per meeting per `POLL_INTERVAL` quickly adds up and there is no
-automatic cleanup. You'll have to delete old rows yourself and make sure your database can
-handle it. On the plus side, those numbers won't contain any personal data, just meeting
-IDs and counters.
-
-Once activated with the `POLL_STATS` setting, the meeting poller will store the current
-user, voice and video stream count per meeting on each poll. You can write your own SQL
-queries to get what you need. A common approach would be to fetch all rows in a certain
-time range, calculate average values per meeting, then group those together by tenant.
-
-Here is an (untested) example query that shows most of the techniques:
+BBBLB can collect and store detailed meeting statistics in the database, allowing you to
+run your own SQL queries to get any metrics you may need. Once activated with the
+`POLL_STATS` setting, the meeting poller will store the current `users`, `voice` and
+`video` counts for each running meeting on each server poll. Those statistics do not
+contain any personal data, which makes this approach very GDPR friendly.
+
+The `POLL_STATS` feature is disabled by default, because the database table will grow by
+one row per meeting per `POLL_INTERVAL` and there is no automatic cleanup. This adds up
+quickly, especially for large or busy clusters. Make sure to delete old rows regularly
+to keep your database size in check.
+
+The `meeting_stats` table is structured similar to a time series database. Each row has
+a timestamp (`ts`), the `uuid` of the meeting, the reuseable external `meeting_id` that
+was used to create the meeting, the tenant (`tenant_fk`), and three metric values named
+`users`, `voice` and `video`.
+
+Here is an (untested) example PostgreSQL query returning some useful aggregations. It
+fetches all rows in a certain time range, calculate min/max/average values per meeting
+(per `uuid`), then groups those together by `tenant_fk` to get meaningfull aggregated
+values per tenant:
 
 .. code:: sql
 
   SELECT
     tenants.name,
-    /* Total number of meeting minutes spent by each participant */ 
-    SUM(users_avg * EXTRACT(epoch FROM started - ended)) / 60,
+    /* Total number of meeting minutes spent by all users combined */ 
+    SUM(users_avg * EXTRACT(epoch FROM duration)) / 60,
     /* Average meeting duration in minutes */ 
-    AVG(EXTRACT(epoch FROM started - ended)) / 60, 
+    AVG(EXTRACT(epoch FROM duration)) / 60, 
     /* Aveage meeting size */ 
     AVG(users_avg),
     /* Maximum meeting size */ 
@@ -80,8 +87,7 @@ Here is an (untested) example query that shows most of the techniques:
       SELECT
         tenant_fk,
         uuid,
-        MIN(ts) AS started,
-        MAX(ts) AS ended,
+        MAX(ts) - MIN(ts) as duration
         AVG(users) AS users_avg
         MAX(users) AS users_max
       FROM meeting_stats