Skip to main content

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​

CategoryKeyWhat's logged
MessagemessageMessage edits, deletes (with original content), bulk deletes
MembermemberJoins, leaves, kicks (via audit log), nickname/avatar changes, role adds/removes, voice joins/leaves/moves/mute/deafen
ServerserverChannel create/delete/rename/topic/slowmode, thread create/delete, emoji create/delete/rename, role create/delete/update, invite create/delete
ModerationmoderationBans, unbans, timeouts, message clears, user data wipes (moderator + reason from the audit log)

Package layout​

FileRole
__init__.pysetup(bot) — registers nine cogs (8 loggers +
LoggerCommands) and the log_toggle application command group
config.pyCategory keys, embed colors, default channel names
database.pyPostgres: messages (message cache), guild_logs (per-guild channel config), log_toggles (per-event toggles), events (history for the web History page + export)
logger.pyLogger.send(guild, category, embed) — resolves the channel, swallows send errors
base.pyBaseLogger cog — every logger cog extends this for send() + audit_entry()
embeds.pyLoggerEmbed — shared embed builders (base, author, field, footer)
messages.pyMessageLogger — caches every message; logs edits/deletes
members.pyMemberLogger — joins, leaves, profile/role changes
channels.pyChannelLogger — channel + thread events
emoji.pyEmojiLogger — emoji create/delete/rename
moderation.pyModerationLogger — bans, unbans, timeouts
commands.py/logs setup, /logs change_channel, /logs settings, /log_toggle
voice.pyVoiceLogger — voice state changes
invites.pyInviteLogger — invite create/delete
roles.pyRoleLogger — role create/delete/update
audit.pyAudit.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).

CommandWhat it doesWho can use it
/logs setupBinds up to 4 existing log channels (or creates them with the opt-in create_channels flag, default off), validated for bot send firstAdministrator
/logs change_channelPoint one category at a different channel (picker for category + channel)Administrator
/logs settingsShow which channel each category logs to, plus disabled eventsEveryone
/log_toggle messageToggle message_edit, message_delete, bulk_deleteAdministrator
/log_toggle memberToggle member_join, member_leave, member_kick, nickname, avatar, role_memberAdministrator
/log_toggle voiceToggle voice_join, voice_leave, voice_move, voice_muteAdministrator
/log_toggle serverToggle channel/thread/emoji/role/invite events (13)Administrator
/log_toggle moderationToggle ban, unban, timeoutAdministrator

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:

  1. Looks up the channel ID from guild_logs for that guild + category.
  2. Returns silently if none is configured (no setup = no logs, no errors).
  3. Falls back to bot.fetch_channel if the channel isn't in cache.
  4. 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_update listeners. MemberLogger (nick/avatar/roles) and ModerationLogger (timeouts) both listen; they check disjoint conditions, so nothing double-logs.
  • Setup is per guild. Each server runs /logs setup once (on the Helper); the config lives in guild_logs, keyed by (guild_id, log_type).