This repository has been archived by the owner on Apr 26, 2024. It is now read-only.
-
-
Notifications
You must be signed in to change notification settings - Fork 2.1k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Add monthly active users documentation (#13617)
* Add monthly active users documentation * changelog * Tidy up notes * more tidyup * Rewrite #1 * link back to mau docs * fix links * s/appservice|AS/application service * further review * a newline * Remove bit about shadow banned users. I think talking about them is confusing, and the current text doesn't imply they get any special treatment. * Update docs/usage/administration/monthly_active_users.md Co-authored-by: Patrick Cloke <clokep@users.noreply.github.com> * Update docs/usage/administration/monthly_active_users.md Co-authored-by: Patrick Cloke <clokep@users.noreply.github.com> Co-authored-by: Brendan Abolivier <babolivier@matrix.org> Co-authored-by: Patrick Cloke <clokep@users.noreply.github.com>
- Loading branch information
1 parent
dcfb006
commit c913e44
Showing
4 changed files
with
88 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1 @@ | ||
Document how ["monthly active users"](https://matrix-org.github.io/synapse/latest/usage/administration/monthly_active_users.html) is calculated and used. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,84 @@ | ||
# Monthly Active Users | ||
|
||
Synapse can be configured to record the number of monthly active users (also referred to as MAU) on a given homeserver. | ||
For clarity's sake, MAU only tracks local users. | ||
|
||
Please note that the metrics recorded by the [Homeserver Usage Stats](../../usage/administration/monitoring/reporting_homeserver_usage_statistics.md) | ||
are calculated differently. The `monthly_active_users` from the usage stats does not take into account any | ||
of the rules below, and counts any users who have made a request to the homeserver in the last 30 days. | ||
|
||
See the [configuration manual](../../usage/configuration/config_documentation.md#limit_usage_by_mau) for details on how to configure MAU. | ||
|
||
## Calculating active users | ||
|
||
Individual user activity is measured in active days. If a user performs an action, the exact time of that action is then recorded. When | ||
calculating the MAU figure, any users with a recorded action in the last 30 days are considered part of the cohort. Days are measured | ||
as a rolling window from the current system time to 30 days ago. | ||
|
||
So for example, if Synapse were to calculate the active users on the 15th July at 13:25, it would include any activity from 15th June 13:25 onwards. | ||
|
||
A user is **never** considered active if they are either: | ||
- Part of the trial day cohort (described below) | ||
- Owned by an application service. | ||
- Note: This **only** covers users that are part of an application service `namespaces.users` registration. The namespace | ||
must also be marked as `exclusive`. | ||
|
||
Otherwise, any request to Synapse will mark the user as active. Please note that registration will not mark a user as active *unless* | ||
they register with a 3pid that is included in the config field `mau_limits_reserved_threepids`. | ||
|
||
The Prometheus metric for MAU is refreshed every 5 minutes. | ||
|
||
Once an hour, Synapse checks to see if any users are inactive (with only activity timestamps later than 30 days). These users | ||
are removed from the active users cohort. If they then become active, they are immediately restored to the cohort. | ||
|
||
It is important to note that **deactivated** users are not immediately removed from the pool of active users, but as these users won't | ||
perform actions they will eventually be removed from the cohort. | ||
|
||
### Trial days | ||
|
||
If the config option `mau_trial_days` is set, a user must have been active this many days **after** registration to be active. A user is in the | ||
trial period if their registration timestamp (also known as the `creation_ts`) is less than `mau_trial_days` old. | ||
|
||
As an example, if `mau_trial_days` is set to `3` and a user is active **after** 3 days (72 hours from registration time) then they will be counted as active. | ||
|
||
The `mau_appservice_trial_days` config further extends this rule by applying different durations depending on the `appservice_id` of the user. | ||
Users registered by an application service will be recorded with an `appservice_id` matching the `id` key in the registration file for that service. | ||
|
||
|
||
## Limiting usage of the homeserver when the maximum MAU is reached | ||
|
||
If both config options `limit_usage_by_mau` and `max_mau_value` is set, and the current MAU value exceeds the maximum value, the | ||
homeserver will begin to block some actions. | ||
|
||
Individual users matching **any** of the below criteria never have their actions blocked: | ||
- Considered part of the cohort of MAU users. | ||
- Considered part of the trial period. | ||
- Registered as a `support` user. | ||
- Application service users if `track_appservice_user_ips` is NOT set. | ||
|
||
Please not that server admins are **not** exempt from blocking. | ||
|
||
The following actions are blocked when the MAU limit is exceeded: | ||
- Logging in | ||
- Sending events | ||
- Creating rooms | ||
- Syncing | ||
|
||
Registration is also blocked for all new signups *unless* the user is registering with a threepid included in the `mau_limits_reserved_threepids` | ||
config value. | ||
|
||
When a request is blocked, the response will have the `errcode` `M_RESOURCE_LIMIT_EXCEEDED`. | ||
|
||
## Metrics | ||
|
||
Synapse records several different prometheus metrics for MAU. | ||
|
||
`synapse_admin_mau:current` records the current MAU figure for native (non-application-service) users. | ||
|
||
`synapse_admin_mau:max` records the maximum MAU as dictated by the `max_mau_value` config value. | ||
|
||
`synapse_admin_mau_current_mau_by_service` records the current MAU including application service users. The label `app_service` can be used | ||
to filter by a specific service ID. This *also* includes non-application-service users under `app_service=native` . | ||
|
||
`synapse_admin_mau:registered_reserved_users` records the number of users specified in `mau_limits_reserved_threepids` which have | ||
registered accounts on the homeserver. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters