change: MeetingStats now have consistent timestamps per poll interval.

Author: defnull

bbblb/model.py

@@ -426,6 +426,9 @@ class MeetingStats(Base):
     __tablename__ = "meeting_stats"
 
     id: Mapped[int] = mapped_column(primary_key=True)
+    #: Timestamp of the poll run. This SHOULD be identical for all
+    #: entries created during the same poll interval, so we can group
+    #: over the timestamp later.
     ts: Mapped[datetime.datetime] = mapped_column(
         DateTime(timezone=True), insert_default=utcnow, nullable=False
     )

bbblb/services/poller.py

@@ -37,6 +37,11 @@ def __init__(self, config: BBBLBConfig):
         self.minsuccess = config.POLL_RECOVER
         self.stats_enabled = config.POLL_STATS
 
+        #: Start of a poll interval. Used as a common timestamp for all
+        #: MeetingStats entries created during a single poll run. This
+        #: allows later grouping by poll interval.
+        self._poll_start = 0.0
+
     async def on_start(self, db: DBContext, locks: LockManager, bbb: BBBHelper):
         self.db = db
         self.lock = locks.create(
@@ -67,12 +72,13 @@ async def poll_loop(self):
 
             if not await self.lock.check():
                 LOG.warning(f"We lost the {self.lock.name!r} lock!?")
-                break
+                return
 
             async with self.db.session() as session:
                 result = await session.execute(model.Server.select())
                 servers = result.scalars()
 
+            self._poll_start = model.utcnow()
             futures = [
                 asyncio.ensure_future(self.poll_one(server.id)) for server in servers
             ]
@@ -160,6 +166,7 @@ async def poll_one(self, server_id):
                     meeting = meetings[meeting_id]
                     meeting_stats.append(
                         model.MeetingStats(
+                            ts=self._poll_start,
                             uuid=meeting.uuid,
                             meeting_id=meeting.external_id,
                             tenant_fk=meeting.tenant_fk,

docs/accounting.rst

@@ -63,27 +63,47 @@ a timestamp (`ts`), the `uuid` of the meeting, the reuseable external `meeting_i
 was used to create the meeting, the owning 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, calculates min/max/avg values per meeting
-(per `uuid`), then groups those together by `tenant_fk` to get meaningfull aggregated
-values per tenant:
+The timestamp (`ts`) will be the exact same for all measurements taken during a single
+poll interval. It marks the start of the poll interval, not the exact time of an
+individual measurement. This is is done on purpose so you can group by the timestamp to
+get a consistend view of the entire cluster at a specific time.
+
+Here is an example that calculates user counts for the entire cluster over time.
+It uses the fact mentioned above that all measurements taken during a single poll interval
+will have the exact same timestamp.
+
+.. code:: sql
+
+    SELECT
+      ts,
+      COUNT(*) as meetings,
+      SUM(users) AS users
+    FROM meeting_stats
+    GROUP BY ts
+    ORDER BY ts
+
+Here is a more complex PostgreSQL example. It fetches all rows in a certain time range,
+calculates min/max/avg values per meeting (per `uuid`), then groups those together by
+`tenant_fk` to get meaningfull aggregated values per tenant.
 
 .. code:: sql
 
   SELECT
-    tenants.name,
+    tenants.name AS tenant,
+    /* Number of meetings */ 
+    COUNT(*) AS meetings,
     /* Total number of meeting minutes spent by all users combined */ 
-    SUM(users_avg * EXTRACT(epoch FROM duration)) / 60,
+    SUM(users_avg * EXTRACT(epoch FROM duration)) / 60 AS meeting_minutes,
     /* Average meeting duration in minutes */ 
-    AVG(EXTRACT(epoch FROM duration)) / 60, 
+    AVG(EXTRACT(epoch FROM duration)) / 60 AS duration_avg, 
     /* Aveage meeting size */ 
-    AVG(users_avg),
+    AVG(users_avg) AS users_avg,
     /* Maximum meeting size */ 
-    MAX(users_max),
+    MAX(users_max) AS users_max,
+    /* Number of meetings with more than 25 users peak */ 
+    COUNT(CASE WHEN users_max > 100 THEN 1 END) AS large_25,
     /* Number of meetings with more than 100 users peak */ 
-    COUNT(CASE WHEN users_max > 100 THEN 1 END),
-    /* Number of meetings */ 
-    COUNT(*)
+    COUNT(CASE WHEN users_max > 100 THEN 1 END) AS large_100
   FROM (
       SELECT
         tenant_fk,