Modlog & Warnings
Relevant source files
The following files were used as context for generating this wiki page:
The Modlog and Warnings systems provide governance and record-keeping for server moderation. The Modlog records specific administrative actions as numbered cases in a designated channel. The Warnings module tracks user behavioral infractions using a point-based system that triggers automated penalties when thresholds are exceeded.
Sources: redbot/cogs/modlog/modlog.py:1-20, redbot/cogs/warnings/warnings.py:1-35, redbot/core/core_commands.py:1150-1160
Warnings Architecture
The Warnings cog manages user infractions through persistent configuration data and hierarchical validation. It tracks infractions per member within a guild and calculates total points to determine if automated actions are necessary.
Warning Process Flow
When a moderator issues a warning, the system validates the hierarchy between the moderator and the target. It then updates the target member's point total and logs the event to the Modlog.
The diagram shows the logic path from command invocation to final storage and notification.
Sources: redbot/cogs/warnings/warnings.py:240-345
Data Structures
The module utilizes two primary configuration levels:
- Guild Level: Stores global rules for the server, including automated actions and predefined reasons.
- Member Level: Tracks individual infractions and running point totals.
| Field | Description | Scope |
|---|---|---|
actions | List of commands to run at point thresholds | Guild |
reasons | Map of reason names to points and descriptions | Guild |
total_points | Running sum of all points issued to a user | Member |
warnings | Collection of specific warning instances | Member |
Sources: redbot/cogs/warnings/warnings.py:38-50
Automated Penalties (Warn Actions)
Automated actions function as command macros triggered by point thresholds. The system evaluates the member's new point total after every warning to see if a threshold is crossed.
Threshold Trigger Logic
- A moderator adds points to a user.
- The system calls
warning_points_add_check. - The system identifies the highest registered action where
points <= current_total. - The system executes the
exceed_commandassociated with that action.
Sources: redbot/cogs/warnings/warnings.py:175-185, redbot/cogs/warnings/warnings.py:330-335
Modlog Case Management
The Modlog provides a persistent interface for viewing and modifying moderation history. Each administrative action (ban, kick, warn, unwarn) creates a unique case number.
Modlog Commands
| Command | Action |
|---|---|
case | Displays full details for a specific case number |
casesfor | Lists all moderation cases associated with a specific member |
reason | Allows moderators to update the justification for an existing case |
listcases | Provides a paginated text list of user history |
Sources: redbot/cogs/modlog/modlog.py:26-110
Case Amendment Workflow
Moderators can update reasons for previous cases. If the editor is not the original moderator, the system records the editor's identity in the amended_by field.
The sequence diagram illustrates how case reasons are updated while maintaining an audit trail of amendments.
Sources: redbot/cogs/modlog/modlog.py:90-115
System Configuration
Global settings for the Modlog system are managed via the modlogset command group. This centralizes control over where logs are sent and which events are tracked.
- Channel Designation: Use
[p]modlogset modlog <channel>to set the destination for log messages. - Action Filtering: Use
[p]modlogset cases <action> <enabled>to toggle case creation for specific types (e.g., enabling logs for kicks but disabling them for mutes). - Reset:
[p]modlogset resetcasesclears all log history for the guild.
Sources: redbot/core/core_commands.py:1165-1250
Data Privacy and Deletion
Both modules implement red_delete_data_for_user to comply with privacy requirements.
Moderator Deletion
If a moderator's account is deleted from Discord, the system sanitizes the logs rather than deleting the infractions. Warning instances replace the mod ID with the hex value 0xDE1 (Deleted Moderator) to maintain record integrity while removing personal identifiable information.
Sources: redbot/cogs/warnings/warnings.py:53-78, redbot/cogs/permissions/permissions.py:100-110
Target Member Deletion
When a target member's data is requested for deletion via a strict user request or a "discord_deleted_user" signal:
- All warning records for that user are cleared.
- The member's point totals are reset to zero.
Sources: redbot/cogs/warnings/warnings.py:55-65, redbot/core/core_commands.py:550-600
Summary
The Modlog and Warnings systems integrate to provide an automated yet reviewable moderation workflow. Modlog ensures transparency through persistent case numbers and channel logs, while Warnings provides a point-based logic engine for scaling behavioral responses. All components adhere to the Discord hierarchy and project-wide data privacy standards.