Collects and analyses activity statistics.
No messages or personally identifiable information are stored by this module, only event counts such as number of messages in each channel on an hour-by-hour basis.
Operation
This module counts various events like messages, voice time, server join/parts, etc. This information is aggregated by anonymous user hash (see below), channel, and hour, in order to allow obtaining statistics like number of unique users per channel, most active hours of the day, etc.
Unique users are recorded on a month-by-month basis, using a cryptographic hash algorithm and a salt in order to ensure this data cannot be traced backwards to a specific user during the collection period.
At the end of each month, all user hashes are replaced with random tokens generated from a cryptographically strong pseudorandom algorithm, ensuring that no connection to the original user (even cryptographically obfuscated) can be made. Furthermore, the salt is regenerated for the next month’s data collection, ensuring that a user cannot be tracked month-to-month even if data is accessed prior to the end of the month. The salt is never made available to moderators or users, and automatically destroyed once it is no longer needed.
File format
userstats
Raw user data is provided as a file attachment in a gzip-compressed Excel-compatible CSV format, containing the following columns:
| # | Column name | Type | Description |
|---|---|---|---|
| 1 | Period | datetime (ISO8601) | The hour during which these events were recorded, in the UTC timezone. |
| 2 | Event | str | Event name. One of: msg, join, part, voice, total_users. |
| 3 | User hash | hex | A string representing a unique user. Rows with the same user hash, recorded in the same month, indicate the same user. |
| 4 | Channel | ’#’ + str | The name of the channel in which the event was recorded. |
| 5 | Count | int | The number of times (or, for voice events, number of seconds) an event was recorded. |
reports
Full reports are provided as a a Discord embed, as shown below. The data contained is the same as the CSV columns, as shown in the table below.
Weekday and hourly reports are provided as a file attachment in a gzip-compressed Excel-compatible CSV format, containing the columns described in the following table.
| # | Column name | Type | Description |
|---|---|---|---|
| 1 | Case | str | For weekday reports, Monday through Sunday. For hourly reports, the hour of the day (in UTC). |
| 2 | Total users | int | Total number of users on the server at the end of the report period. |
| 3 | Active users | int | Number of unique users who sent any messages during the report period. |
| 4 | Voice users | int | Number of unique users who spent at least 1 second in voice chat. |
| 5 | Joins | int | Number of users who joined the server. This includes users who part and re-join in the report period. |
| 6 | Parts | int | Number of users who left the server. |
| 7 | Messages | int | Total number of text messages sent. |
| 8 | Messages/user | float | Number of messages sent per active user. |
| 9 | (stdev) | float | Standard deviation for column 8. |
| 10 | Voice man-hours | float (hours) | Total collective time, in man-hours, spent in voice channels. |
| 11 | Voice hours/user | float (hours) | Time spent, in hours, per user in voice channels. |
| 12 | (stdev) | float (hours) | Standard deviation for column 11. |
1. userstats
Retrieve a CSV dump of stats for a date or range of dates.
If a range of dates is specified, the data retrieved is up to and excluding the second date. A day starts at midnight UTC.
Note that if the range crosses month boundaries (e.g. March to April), then the unique user IDs can be correlated between each other only within the same month. The same user will have different IDs in different months. This is used as a anonymisation method, to avoid long-term tracking of a unique user while allowing monthly trend analyses.
This will generate and upload a CSV file, and could take some time. Please avoid calling this function multiple times for the same data or requesting giant ranges.
The file is compressed using gzip. Windows users should use a modern archiving programme like 7zip; macOS users can open these files natively. Linux users know the drill.
Usage: .userstats [daterange]
Parameters
- [daterange]
- Optional. The period to retrieve stats for. Can be a single date (period of 24 hours is assumed), or a range of dates in the form
date1 to date2. Each date can be specified in the ISO format (2018-01-12), in English with or without abbreviations (12 Jan 2018), or as a relative date (5 days ago). Default: last month
Details
- Members
- Moderators, Administrators.
- Channels
- Mod channels.
Examples
.userstats 2018-01-12.userstats yesterday.userstats 2018-01-12 to 2018-01-14.userstats 3 days ago to yesterday.userstats 2018-01-01 to 7 days ago
1.1. userstats report
Generate and show a statistics report for a date or range of dates.
If a range of dates is specified, the data retrieved is up to and excluding the second date. A day starts at midnight UTC.
The date range cannot cross the boundary of one month, as it is not possible to calculate per-user statistics across multiple months.
This will read and process the raw data to generate stats, and could take some time. Please avoid calling this function multiple times for the same data or requesting giant ranges.
The file is compressed using gzip. Windows users should use a modern archiving programme like 7zip; macOS users can open these files natively. Linux users know the drill.
Usage: .userstats report <type_> <channel> [daterange]
Parameters
- <type>
- “full”, “weekday” or “hourly”. Report type. “full” calculates overall stats; “weekday” generates stats for each day of the week (Monday, etc.); “hourly” generates stats for each hour of the day across the entire period.
- <channel>
- string or “all”. The name of a channel on the server, or “all”.
- [daterange]
- string. Optional. The range of dates to generate the report from. Same format as in userstats.
Details
- Members
- Moderators, Administrators.
- Channels
- Mod channels.
Examples
.report full all 2018-01-12.report full all yesterday.report full.report weekday all 3 days ago to yesterday.report hourly