Logger internals
Source: cogs/Logger/. State: the shared Postgres database (havenly,
PostgreSQL 17 in Docker). The old SQLite files (data/message_log.db,
bot.db) are frozen legacy copies from the 2026-11-12 cutover — nothing
writes to them any more.
The Logger records server events to dedicated log channels — one channel per category, configured per guild. It is separate from the Watch List system (which mirrors watched users' messages); the Logger covers server-wide events.
Categories
| Category | Key | What's logged |
|---|---|---|
| Message | message | Message edits, deletes (with original content), bulk deletes |
| Member | member | Joins, leaves, kicks (via audit log), nickname/avatar changes, role adds/removes, voice joins/leaves/moves/mute/deafen |
| Server | server | Channel create/delete/rename/topic/slowmode, thread create/delete, emoji create/delete/rename, role create/delete/update, invite create/delete |
| Moderation | moderation | Bans, unbans, timeouts, message clears, user data wipes (moderator + reason from the audit log) |
Package layout
| File | Role |
|---|---|
__init__.py | setup(bot) — registers nine cogs (8 loggers + |
LoggerCommands) and the log_toggle application command group | |
config.py | Category keys, embed colors, default channel names |
database.py | Postgres: messages (message cache), guild_logs (per-guild channel config), log_toggles (per-event toggles), events (history for the web History page + export) |
logger.py | Logger.send(guild, category, embed) — resolves the channel, swallows send errors |
base.py | BaseLogger cog — every logger cog extends this for send() + audit_entry() |
embeds.py | LoggerEmbed — shared embed builders (base, author, field, footer) |
messages.py | MessageLogger — caches every message; logs edits/deletes |
members.py | MemberLogger — joins, leaves, profile/role changes |
channels.py | ChannelLogger — channel + thread events |
emoji.py | EmojiLogger — emoji create/delete/rename |
moderation.py | ModerationLogger — bans, unbans, timeouts |
commands.py | /logs setup, /logs change_channel, /logs settings, /log_toggle |
voice.py | VoiceLogger — voice state changes |
invites.py | InviteLogger — invite create/delete |
roles.py | RoleLogger — role create/delete/update |
audit.py | Audit.latest() — audit-log lookup matched by target ID |
Commands
All Logger commands run on Havenly Helper — the setup and the toggles live there. The event logging itself is done by the main bot (see Which bot does the logging below).
| Command | What it does | Who can use it |
|---|---|---|
/logs setup | Binds up to 4 existing log channels (or creates them with the opt-in create_channels flag, default off), validated for bot send first | Administrator |
/logs change_channel | Point one category at a different channel (picker for category + channel) | Administrator |
/logs settings | Show which channel each category logs to, plus disabled events | Everyone |
/log_toggle message | Toggle message_edit, message_delete, bulk_delete | Administrator |
/log_toggle member | Toggle member_join, member_leave, member_kick, nickname, avatar, role_member | Administrator |
/log_toggle voice | Toggle voice_join, voice_leave, voice_move, voice_mute | Administrator |
/log_toggle server | Toggle channel/thread/emoji/role/invite events (13) | Administrator |
/log_toggle moderation | Toggle ban, unban, timeout | Administrator |
Which bot does the logging
The Logger package loads on both bots, but its 8 listener cogs are
gated to the main bot only — the worker loads the package just for the
/logs and /log_toggle commands. The prune loop is main-only too.
So events are logged exactly once: the Helper never sees them, and
nothing double-logs. (The worker journal shows zero Logger lines since
the 2026-11-13 split.)
How sending works
Cogs never send directly. They build an embed with LoggerEmbed helpers
and call self.send(guild, category, embed) (from BaseLogger). That
goes through Logger.send(), which:
- Looks up the channel ID from
guild_logsfor that guild + category. - Returns silently if none is configured (no setup = no logs, no errors).
- Falls back to
bot.fetch_channelif the channel isn't in cache. - Swallows
Forbidden/NotFound/HTTPException— a deleted channel or lost permission never crashes an event handler.
Message cache
MessageLogger.on_message stores every guild message in the messages
table in Postgres. On delete, the logger prefers the live Message
object but falls back to the cached row, so deletes show the original
content even for uncached messages. Bulk deletes use
on_raw_bulk_message_delete and log a count.
Audit log matching
Audit.latest(guild, action, target_id) fetches recent audit-log entries
for an action and returns the first one whose target matches target_id.
This keeps the "Moderator" / "Reason" fields on ban/timeout/channel
embeds accurate instead of grabbing an unrelated recent entry.
Per-event toggles
Every log event has a toggle key (see EVENT_GROUPS in config.py —
29 events total). They default to on. /log_toggle is a command group
with per-category subcommands (/log_toggle voice, etc.) because Discord
caps option choices at 25 — one flat list wouldn't fit. Each subcommand flips one;
db.is_enabled(guild_id, key) is checked at the top of every handler,
and /logs settings lists what's currently disabled. The state lives in
the log_toggles table in Postgres, keyed by (guild_id, event_key).
History + export (web)
The Logger History page reads the events table (capped at 5000 rows).
Its Export CSV button writes real columns — id, guild_id, timestamp
(ISO UTC), category, event_type, summary — with a UTF-8 BOM for Excel
and a -user-<id> filename suffix when filtered, and it respects the
user/channel/date filters. Logger.send records a rich summary
(description + author line + Field: value lines, 2000 chars) so
per-user export works for events logged after the restart that picked
the fix up; older rows have NULL summaries and can't match user/channel
filters. Export dates are UTC.
Kick detection
on_member_remove can't tell a kick from a leave on its own, so it
checks the audit log for a kick entry targeting that user within the
last 15 seconds. Kicks go to the 🚨 moderation channel as
"👢 Member Kicked" (with moderator + reason); plain leaves stay in 👥.
Gotchas
- Message Content intent. The Logger needs the privileged Message
Content intent to see message text. It's set in
bot.py(intents.message_content = True) and must also be toggled on in the Discord Developer Portal (Bot → Privileged Gateway Intents), or all logged content will be empty. - Two
on_member_updatelisteners.MemberLogger(nick/avatar/roles) andModerationLogger(timeouts) both listen; they check disjoint conditions, so nothing double-logs. - Setup is per guild. Each server runs
/logs setuponce (on the Helper); the config lives inguild_logs, keyed by(guild_id, log_type).