Analytics - Leaderboards

An auto-updating leaderboard ranks members by one kind of activity on a schedule you set. Each time it runs, it can post a leaderboard image to a channel and give a role to exactly the members at the top, taking it from anyone who dropped off.

This is separate from the Levels module's public web leaderboard, which ranks XP.

Creating a leaderboard

1. Open Analytics > Leaderboards and click Create.
2. Give it a Name and pick the Metric: Messages, Reactions, Voice Time, Commands, Emoji Usage, Threads Created or Successful Invites.
3. Set Top Members: how many members it ranks (1 to 100, default 3).
4. Set the Schedule: Every N days, weeks, months or years, On a day, At a time, in the server's timezone. The line under it spells it out, for example "Every week on Monday at 18:00 Europe/London".
5. Choose what happens on each run (either or both):
   • Role (optional): the top members get this role; members who are no longer in the top lose it.
   • Post Channel (optional): the leaderboard is posted here.
6. Optionally narrow what counts:
   • Channel Filter: Allowlist counts only activity in the listed channels, Blocklist ignores activity in them.
   • Role Filter: Allowlist ranks only members with a listed role, Blocklist leaves them out.
7. Pick the Post Message Template: the default (@analytics.leaderboard.post) or your own; Create template opens the Message Builder and brings you back. See Variables.
8. Click Create (Save Changes when you edit an existing leaderboard).

The switch on a leaderboard pauses or resumes it, Template edits its post template, the pencil edits it and the trash icon deletes it.

What a run counts

Each run ranks activity over the length of one interval, ending now: a weekly leaderboard covers the last 7 days, a monthly one the last 30. Like every activity ranking it:

• leaves out members who have left the server, and members who opted out of that kind of activity;
• only sees the last 30 days of per-member activity (the anonymization window), so a monthly or yearly leaderboard ranks the last 30 days.

The bot checks for due leaderboards every minute. After a run, the next one is scheduled whether or not it worked. A leaderboard that fails five runs in a row (for example because the bot cannot post in the channel or give the role) is paused and shows Paused, and a Pause Leaderboard entry with the bot as the actor goes to the Analytics logs; fix the cause and switch it back on.