Modlogs

Modlogs are the staff-facing audit trail for the bot. They show what happened, where it happened, who triggered it, and enough context for staff to make a decision without digging through every channel.

Best setup

Use separate channels for Actions, Member Presence, and Voice if the server is busy. Small servers can safely point several buckets at the same staff log channel.

Privacy note

Bot logs are privacy-safe internally: structured logs use request IDs and hashed PIDs instead of raw Discord IDs. Discord embeds may still show useful staff-facing mentions, channel mentions, and short message snippets because those are visible inside the server log channels.

🧭 Quick setup

Run these as an admin/helper with the right bot capability:

!config modlog enable
!config modlog set main #mod-log
!config modlog set actions #mod-actions
!config modlog set events #server-events
!config modlog set alerts #alerts
!config modlog set voice #voice-log
!config modlog set member_presence #member-log
!config modlog test

Then check the channels and confirm each configured bucket received a test embed.

You do not need six separate channels

The buckets are routes, not required channels. You can point multiple buckets at the same channel if you want a simpler setup.

🪣 Bucket guide

Bucket	What it is for	Good channel name
main	General fallback/default modlog route.	#mod-log
actions	Staff actions and important moderation events, including message edits/deletes and member updates from the current event cog.	#mod-actions
events	General server event routing where used by other cogs.	#server-events
alerts	Higher priority alerts and warnings where used by other cogs.	#alerts
voice	Voice-related logs where voice logging is enabled.	#voice-log
member_presence	Member joins and leaves.	#member-log

Current live behaviour

The current modlog_events.py routes message edits, message deletes, and member updates to the actions bucket. Member joins and leaves go to member_presence.

⚙️ Main commands

Command	What it does
!config modlog show	Shows whether modlogs are enabled and where each bucket points.
!config modlog status	Same as show.
!config modlog enable	Turns modlog routing on for the guild.
!config modlog on	Same as enable.
!config modlog disable	Turns modlog routing off for the guild.
!config modlog off	Same as disable.
!config modlog set <bucket> #channel	Sets a bucket to a channel.
!config modlog test	Sends test embeds to configured buckets.
!config modlog check	Same as test.

Set bucket channels

Use this format:

!config modlog set <bucket> #channel

Examples:

!config modlog set actions #mod-actions
!config modlog set member_presence #member-log
!config modlog set voice #voice-log

Supported buckets:

main
actions
events
alerts
voice
member_presence

Channel mention required

For set, use an actual Discord channel mention like #mod-actions. The live command resolver expects a mentioned channel.

👀 What gets logged

Message edits

When a member edits a message, the bot logs:

• author
• channel
• old content
• new content
• message jump link where available

The message content is trimmed so long messages do not flood the log.

Message deletes

When a member message is deleted, the bot logs:

• author
• channel
• deleted content snippet

The bot skips bot messages and skips messages that look like bot commands. It also honours the text-channel exclude list.

Member joins and leaves

Member join/leave events go to the member_presence bucket.

Join logs include:

• member mention
• account creation time
• avatar thumbnail when available

Leave logs include:

• member mention
• when they joined the server, if available
• avatar thumbnail when available

Member updates

Member update logs currently cover:

• nickname changes
• roles added
• roles removed

Role changes are shown by role name in the embed. The structured logs stay privacy-safe.

🚫 Excluding noisy channels

Text channel exclude list

Use this when a channel creates too much message-delete noise.

!config modlog text-exclude list
!config modlog text-exclude add #channel
!config modlog text-exclude remove #channel

Examples:

!config modlog text-exclude add #bot-spam
!config modlog text-exclude remove #bot-spam

What this affects

Text excludes are for message delete logging. They do not disable every possible log from that channel.

Voice channel exclude list

Use this for noisy voice channels such as AFK, staging, or temporary voice areas.

!config modlog voice-exclude list
!config modlog voice-exclude add <voice-channel>
!config modlog voice-exclude remove <voice-channel>

The voice channel can be provided as:

• a channel mention
• a channel ID
• the exact channel name

Examples:

!config modlog voice-exclude add General Voice
!config modlog voice-exclude add 123456789012345678
!config modlog voice-exclude remove General Voice

Exact names only

If you use a channel name, it must match the voice channel name exactly, apart from case.

🧪 Testing and checking

After changing modlog routing, run:

!config modlog show
!config modlog test

The test command tries each configured bucket and sends a simple test embed. If nothing is configured, it tells you to set buckets first.

A good setup test looks like this:

!config modlog show

Expected result:

Enabled: ON
Main: #mod-log
Actions: #mod-actions
Events: #server-events
Alerts: #alerts
Voice: #voice-log
Member Presence: #member-log

Then:

!config modlog test

Expected result:

Test sent. Check your configured mod-log channels.

🔐 Permissions needed

The staff member running config commands needs the bot's admin capability for config commands.

The bot needs these Discord permissions in every modlog channel:

• View Channel
• Send Messages
• Embed Links
• Read Message History is useful for troubleshooting, although embeds are sent directly

Common issue

If !config modlog test says it sent the test but a channel shows nothing, check the bot's channel permissions and role order first.

🧹 Recommended server layout

For a small or quiet server:

#mod-log         main, actions, events, alerts
#member-log      member_presence
#voice-log       voice

For a larger staff team:

#mod-log
#mod-actions
#server-events
#alerts
#voice-log
#member-log

For a very noisy server:

#mod-actions     warnings, bans, config changes, message deletes
#member-log      joins and leaves
#voice-log       voice changes
#alerts          important automated alerts
#server-events   lower priority events

🛠️ Troubleshooting

Message deletes are not showing

Check these first:

1. !config modlog show
2. Confirm actions has a channel.
3. Confirm modlogs are enabled.
4. Check the channel is not excluded with !config modlog text-exclude list.
5. Check the deleted message was not from a bot and was not a bot command message.

Member joins/leaves are not showing

Check that member_presence is configured:

!config modlog set member_presence #member-log
!config modlog test

The test command works, but real logs do not appear

The channel route is probably fine. Check whether the event type is filtered, ignored, or handled by another cog. Message delete logging skips bot messages and bot-command-looking messages by design.

The wrong bucket is being used

Run !config modlog show and confirm the bucket routes. Current message edit/delete and member update events use actions; member joins/leaves use member_presence.

Too much noise

Use channel excludes first instead of disabling modlogs completely:

!config modlog text-exclude add #bot-spam
!config modlog voice-exclude add AFK

🧾 Staff checklist

Before relying on modlogs for staff work:

• [ ] !config modlog enable has been run.
• [ ] actions points to a staff-only channel.
• [ ] member_presence points to the join/leave log channel.
• [ ] voice points to the voice log channel, if voice logging is used.
• [ ] !config modlog test sends embeds successfully.
• [ ] Noisy text channels are excluded only where needed.
• [ ] Noisy voice channels are excluded only where needed.
• [ ] Staff understand that Discord embeds may show message snippets, while internal logs remain privacy-safe.

🧠 Notes for future cleanup

Code/documentation audit note

The live config command help still says “3 buckets” in one docstring, but the command now supports six routes: main, actions, events, alerts, voice, and member_presence. That is a code-help wording cleanup for later, not a docs blocker.