|
| 1 | +Room and User Statistics |
| 2 | +======================== |
| 3 | + |
| 4 | +Synapse maintains room and user statistics (as well as a cache of room state), |
| 5 | +in various tables. These can be used for administrative purposes but are also |
| 6 | +used when generating the public room directory. |
| 7 | + |
| 8 | + |
| 9 | +# Synapse Developer Documentation |
| 10 | + |
| 11 | +## High-Level Concepts |
| 12 | + |
| 13 | +### Definitions |
| 14 | + |
| 15 | +* **subject**: Something we are tracking stats about – currently a room or user. |
| 16 | +* **current row**: An entry for a subject in the appropriate current statistics |
| 17 | + table. Each subject can have only one. |
| 18 | +* **historical row**: An entry for a subject in the appropriate historical |
| 19 | + statistics table. Each subject can have any number of these. |
| 20 | + |
| 21 | +### Overview |
| 22 | + |
| 23 | +Stats are maintained as time series. There are two kinds of column: |
| 24 | + |
| 25 | +* absolute columns – where the value is correct for the time given by `end_ts` |
| 26 | + in the stats row. (Imagine a line graph for these values) |
| 27 | + * They can also be thought of as 'gauges' in Prometheus, if you are familiar. |
| 28 | +* per-slice columns – where the value corresponds to how many of the occurrences |
| 29 | + occurred within the time slice given by `(end_ts − bucket_size)…end_ts` |
| 30 | + or `start_ts…end_ts`. (Imagine a histogram for these values) |
| 31 | + |
| 32 | +Stats are maintained in two tables (for each type): current and historical. |
| 33 | + |
| 34 | +Current stats correspond to the present values. Each subject can only have one |
| 35 | +entry. |
| 36 | + |
| 37 | +Historical stats correspond to values in the past. Subjects may have multiple |
| 38 | +entries. |
| 39 | + |
| 40 | +## Concepts around the management of stats |
| 41 | + |
| 42 | +### Current rows |
| 43 | + |
| 44 | +Current rows contain the most up-to-date statistics for a room. |
| 45 | +They only contain absolute columns |
| 46 | + |
| 47 | +### Historical rows |
| 48 | + |
| 49 | +Historical rows can always be considered to be valid for the time slice and |
| 50 | +end time specified. |
| 51 | + |
| 52 | +* historical rows will not exist for every time slice – they will be omitted |
| 53 | + if there were no changes. In this case, the following assumptions can be |
| 54 | + made to interpolate/recreate missing rows: |
| 55 | + - absolute fields have the same values as in the preceding row |
| 56 | + - per-slice fields are zero (`0`) |
| 57 | +* historical rows will not be retained forever – rows older than a configurable |
| 58 | + time will be purged. |
| 59 | + |
| 60 | +#### Purge |
| 61 | + |
| 62 | +The purging of historical rows is not yet implemented. |
0 commit comments