feat: add user metrics

itsoyou · itsoyou · commit b14601b73b3a · 2025-10-07T19:10:08.000+02:00
diff --git a/synapse/metrics/common_usage_metrics.py b/synapse/metrics/common_usage_metrics.py
@@ -37,12 +37,44 @@
     labelnames=[SERVER_NAME_LABEL],
 )
 
+# Gauge for users
+users_in_status_gauge = Gauge(
+    "synapse_user_count",
+    "Number of users in active, deactivated, suspended, and locked status",
+    ["status", SERVER_NAME_LABEL],
+)
+
+users_in_time_ranges_gauge = Gauge(
+    "synapse_active_users",
+    "Number of active users in time ranges in 24h, 7d, and 30d",
+    ["time_range", SERVER_NAME_LABEL],
+)
+
+# We may want to add additional ranges in the future.
+retained_users_gauge = Gauge(
+    "synapse_retained_users",
+    "Number of retained users in 30d",
+    ["time_range", SERVER_NAME_LABEL],
+)
+
 
 @attr.s(auto_attribs=True)
 class CommonUsageMetrics:
     """Usage metrics shared between the phone home stats and the prometheus exporter."""
 
+    # active users in time ranges
     daily_active_users: int
+    weekly_active_users: int
+    monthly_active_users: int
+
+    # user counts in different states
+    active_users: int
+    deactivated_users: int
+    suspended_users: int
+    locked_users: int
+
+    # retained users in time ranges
+    monthly_retained_users: int
 
 
 class CommonUsageMetricsManager:
@@ -82,9 +114,20 @@ async def _collect(self) -> CommonUsageMetrics:
         use if it doesn't exist yet, or update it.
         """
         dau_count = await self._store.count_daily_users()
+        wau_count = await self._store.count_weekly_users()
+        mau_count = await self._store.count_monthly_users()
+
+        user_metric = await self._store.get_user_count_per_status()
 
         return CommonUsageMetrics(
             daily_active_users=dau_count,
+            weekly_active_users=wau_count,
+            monthly_active_users=mau_count,
+            active_users=user_metric.get("active", 0),
+            deactivated_users=user_metric.get("deactivated", 0),
+            suspended_users=user_metric.get("suspended", 0),
+            locked_users=user_metric.get("locked", 0),
+            monthly_retained_users=user_metric.get("monthly_retained", 0),
         )
 
     async def _update_gauges(self) -> None:
@@ -94,3 +137,28 @@ async def _update_gauges(self) -> None:
         current_dau_gauge.labels(
             **{SERVER_NAME_LABEL: self.server_name},
         ).set(float(metrics.daily_active_users))
+
+        time_range_to_metric = {
+            "24h": metrics.daily_active_users,
+            "7d": metrics.weekly_active_users,
+            "30d": metrics.monthly_active_users,
+        }
+        for time_range, _metric in time_range_to_metric.items():
+            users_in_time_ranges_gauge.labels(
+                time_range=time_range, **{SERVER_NAME_LABEL: self.server_name}
+            ).set(float(_metric))
+
+        status_to_metric = {
+            "active": metrics.active_users,
+            "deactivated": metrics.deactivated_users,
+            "suspended": metrics.suspended_users,
+            "locked": metrics.locked_users,
+        }
+        for status, _metric in status_to_metric.items():
+            users_in_status_gauge.labels(
+                status=status, **{SERVER_NAME_LABEL: self.server_name}
+            ).set(float(_metric))
+
+        retained_users_gauge.labels(
+            time_range="30d", **{SERVER_NAME_LABEL: self.server_name}
+        ).set(float(metrics.monthly_retained_users))
diff --git a/synapse/storage/databases/main/metrics.py b/synapse/storage/databases/main/metrics.py
@@ -229,6 +229,15 @@ async def count_daily_users(self) -> int:
             "count_daily_users", self._count_users, yesterday
         )
 
+    async def count_weekly_users(self) -> int:
+        """
+        Counts the number of users who used this homeserver in the last 7 days.
+        """
+        seven_days_ago = int(self._clock.time_msec()) - (1000 * 60 * 60 * 24 * 7)
+        return await self.db_pool.runInteraction(
+            "count_weekly_users", self._count_users, seven_days_ago
+        )
+
     async def count_monthly_users(self) -> int:
         """
         Counts the number of users who used this homeserver in the last 30 days.
@@ -473,3 +482,57 @@ def _generate_user_daily_visits(txn: LoggingTransaction) -> None:
         await self.db_pool.runInteraction(
             "generate_user_daily_visits", _generate_user_daily_visits
         )
+
+    async def get_user_count_per_status(self) -> Dict[str, int]:
+        def _get_user_count_per_status(txn: LoggingTransaction) -> Dict[str, int]:
+            sql = """
+                SELECT
+                    SUM(CASE WHEN deactivated = 0 AND locked = FALSE AND suspended = FALSE THEN 1 ELSE 0 END) AS active_users,
+                    SUM(CASE WHEN deactivated = 1 THEN 1 ELSE 0 END) AS deactivated_users,
+                    SUM(CASE WHEN suspended = TRUE THEN 1 ELSE 0 END) AS suspended_users,
+                    SUM(CASE WHEN locked = TRUE THEN 1 ELSE 0 END) AS locked_users
+                FROM users;
+            """
+            txn.execute(sql)
+            row = txn.fetchone()
+            if not row:
+                logger.warning("No results from get_user_count_per_status")
+            metrics = {
+                "active": row[0] if row is not None else 0,
+                "deactivated": row[1] if row is not None else 0,
+                "suspended": row[2] if row is not None else 0,
+                "locked": row[3] if row is not None else 0,
+            }
+
+            sql = """
+                SELECT COUNT(*)
+                FROM (
+                    SELECT user_id
+                    FROM user_daily_visits
+                    WHERE timestamp > ? AND timestamp < ?
+                    GROUP BY user_id
+                    HAVING max(timestamp) - min(timestamp) > ?
+                ) AS r30_users;
+            """
+            thirty_days_in_ms = 86400 * 30 * 1000
+            now_ms = int(self._clock.time()) * 1000
+            sixty_days_ago_in_ms = now_ms - 2 * thirty_days_in_ms
+            one_day_from_now_in_ms = now_ms + (86400 * 1000)
+            txn.execute(
+                sql,
+                (
+                    sixty_days_ago_in_ms,
+                    one_day_from_now_in_ms,
+                    thirty_days_in_ms,
+                ),
+            )
+            (count,) = cast(Tuple[int], txn.fetchone())
+            if not count:
+                logger.warning("No results from get_user_count_per_status")
+                metrics["monthly_retained"] = 0
+            metrics["monthly_retained"] = count
+            return metrics
+
+        return await self.db_pool.runInteraction(
+            "get_user_count_per_status", _get_user_count_per_status
+        )
diff --git a/tests/metrics/test_common_usage_metrics.py b/tests/metrics/test_common_usage_metrics.py
@@ -0,0 +1,195 @@
+from twisted.test.proto_helpers import MemoryReactor
+
+from synapse.rest import admin, login, register, room
+from synapse.server import HomeServer
+from synapse.types import create_requester
+from synapse.util import Clock
+
+from tests.unittest import FederatingHomeserverTestCase
+
+
+class CommonUsageMetricsManagerTestCase(FederatingHomeserverTestCase):
+    """
+    Tests for the CommonUsageMetricsManager.
+    """
+
+    servlets = [
+        admin.register_servlets,
+        admin.register_servlets_for_client_rest_resource,
+        room.register_servlets,
+        register.register_servlets,
+        login.register_servlets,
+    ]
+
+    def prepare(
+        self, reactor: MemoryReactor, clock: Clock, homeserver: HomeServer
+    ) -> None:
+        self.manager = homeserver.get_common_usage_metrics_manager()
+        self.admin_user = self.register_user("admin", "pass", admin=True)
+        self.admin_token = self.login(self.admin_user, "pass")
+
+    def _create_active_user(self, prefix: str, i: int) -> str:
+        """
+        Create given number of active users.
+        """
+        username = "%s_active_user_%d" % (prefix, i)
+        self.register_user(
+            username=username,
+            password="test",
+        )
+        user_tok = self.login(username=username, password="test")
+        room_id = self.helper.create_room_as(room_creator=username, tok=user_tok)
+        self.helper.send(room_id, "message", tok=user_tok)
+        return user_tok
+
+    def test_users_in_status_gauge_update(self) -> None:
+        """
+        Test that the users_in_status_gauge updates correctly.
+        """
+        metrics = self.get_success(self.manager.get_metrics())
+
+        # Check initial values
+        self.assertEqual(metrics.active_users, 1)  # 1 admin
+        self.assertEqual(metrics.deactivated_users, 0)
+        self.assertEqual(metrics.suspended_users, 0)
+        self.assertEqual(metrics.locked_users, 0)
+
+        # Create an active user
+        self._create_active_user("t", 1)
+
+        # Create a deactivated user
+        user_mxid = self.register_user(
+            username="deactivated_user",
+            password="test",
+        )
+        self.login(username=user_mxid, password="test")
+        deactivate_handler = self.hs.get_deactivate_account_handler()
+        self.get_success(
+            deactivate_handler.deactivate_account(
+                user_mxid, erase_data=False, requester=create_requester(self.admin_user)
+            )
+        )
+
+        # Create a suspended user
+        user_mxid = self.register_user(
+            username="suspended_user",
+            password="test",
+        )
+        self.login("suspended_user", "test")
+        channel = self.make_request(
+            "PUT",
+            f"/_synapse/admin/v1/suspend/{user_mxid}",
+            {"suspend": True},
+            access_token=self.admin_token,
+        )
+        self.assertEqual(channel.code, 200)
+        self.assertEqual(channel.json_body, {f"user_{user_mxid}_suspended": True})
+
+        # Create a locked user
+        user_mxid = self.register_user(
+            username="locked_user",
+            password="test",
+        )
+        self.login(username=user_mxid, password="test")
+        self.get_success(
+            self.hs.get_datastores().main.set_user_locked_status(user_mxid, True)
+        )
+
+        # Wait for the metrics to be updated
+        self.reactor.advance(5 * 60)
+        metrics = self.get_success(self.manager.get_metrics())
+
+        self.assertEqual(metrics.active_users, 2)  # 1 admin and 1 active user
+        self.assertEqual(metrics.deactivated_users, 1)
+        self.assertEqual(metrics.suspended_users, 1)
+        self.assertEqual(metrics.locked_users, 1)
+
+    def test_users_in_time_ranges_gauge_update(self) -> None:
+        """
+        Test that the users_in_time_ranges_gauge updates correctly.
+        """
+        metrics = self.get_success(self.manager.get_metrics())
+
+        # Check initial values
+        self.assertEqual(metrics.daily_active_users, 0)
+        self.assertEqual(metrics.weekly_active_users, 0)
+        self.assertEqual(metrics.monthly_active_users, 0)
+
+        # Simulate active users per time range
+        # create four monthly active users.
+        for i in range(4):
+            self._create_active_user("monthly", i)
+            self.reactor.advance(60 * 60 * 24 * 5)  # Simulate time passing by 5 days
+        # create five weekly active users.
+        for i in range(5):
+            self._create_active_user("weekly", i)
+            self.reactor.advance(60 * 60 * 24)  # Simulate time passing by 1 day
+
+        # create five daily active users.
+        for i in range(5):
+            self._create_active_user("daily", i)
+            self.reactor.advance(60 * 60)  # Simulate time passing by 1 hour
+
+        channel = self.make_request(
+            "GET",
+            "/_synapse/admin/v2/users",
+            access_token=self.admin_token,
+        )
+        self.assertEqual(200, channel.code)
+        self.assertEqual(
+            len(channel.json_body["users"]), 15
+        )  # 5 daily, 5 weekly, 4 monthly, 1 admin
+
+        # Wait for the metrics to be updated
+        self.reactor.advance(5 * 60)
+        metrics = self.get_success(self.manager.get_metrics())
+
+        self.assertEqual(metrics.daily_active_users, 6)  # 5 daily + 1 admin
+        self.assertEqual(
+            metrics.weekly_active_users, 11
+        )  # 5 weekly + 5 daily + 1 admin
+        self.assertEqual(
+            metrics.monthly_active_users, 15
+        )  # 4 monthly + 5 weekly + 5 daily + 1 admin
+
+    def test_retained_users_gauge_update(self) -> None:
+        """
+        Test that the retained users gauge updates correctly.
+        """
+        # start the user_daily_visits table update loop
+        self.clock.looping_call(
+            self.hs.get_datastores().main.generate_user_daily_visits,
+            5 * 60 * 1000,
+        )
+        metrics = self.get_success(self.manager.get_metrics())
+
+        # Check initial values
+        self.assertEqual(metrics.monthly_retained_users, 0)
+
+        # Simulate retained users
+        for i in range(5):
+            self._create_active_user("retained", i)
+
+        # Give time for user_daily_visits table to be updated.
+        self.reactor.advance(60 * 5)
+
+        # Simulate time passing by 31 days
+        self.reactor.advance(60 * 60 * 24 * 31)
+
+        for i in range(5):
+            user_tok = self.login(
+                username="retained_active_user_%s" % i, password="test"
+            )
+            room_id = self.helper.create_room_as(
+                room_creator="retained_active_user_%s" % i, tok=user_tok
+            )
+            self.helper.send(room_id, "new message", tok=user_tok)
+
+        # Let another user_daily_visits update occur
+        self.reactor.advance(60 * 5)
+
+        # Wait for the metrics to be updated
+        self.reactor.advance(5 * 60)
+        metrics = self.get_success(self.manager.get_metrics())
+
+        self.assertEqual(metrics.monthly_retained_users, 5)
