Logging System
Relevant source files
The following files were used as context for generating this wiki page:The logging system in Amina is a comprehensive, multi-layered framework designed to provide crucial information for both developers and server administrators. It consists of two primary branches: an internal application logging mechanism for debugging and error tracking, and a server-facing guild event logging system for moderation and audit trails. The system is highly configurable, allowing administrators to fine-tune which events are tracked and where the logs are sent.
This document outlines the architecture of both logging systems, their configuration, the data models they use, and how they are integrated into various parts of the bot's functionality, such as moderation, automod, and event handling.
System Architecture
Amina's logging is divided into distinct paths based on the type and purpose of the log.
The diagram below illustrates the high-level architecture of the different logging flows within the application.
Internal Application Logging
The internal logging system is managed by the Logger class and is intended for developers to monitor the bot's health, debug issues, and track errors. It utilizes pino for structured, high-performance logging.
Sources: src/helpers/Logger.ts
Core Components
pinoLogger: The core logging library, configured to be asynchronous and efficient.- Multi-stream Transport: Logs are sent to multiple destinations simultaneously:
- A "pretty" formatted stream to the console for real-time development monitoring.
- A file stream that saves all logs to a date-stamped file (e.g.,
logs/combined-2025.12.5.log).
- Webhook Integration: For critical errors, a Discord webhook is used to send immediate notifications. This is configured via
secret.LOGS_WEBHOOK. - Error Tracking Service:
Honeybadgeris integrated to provide detailed error reports, stack traces, and contextual information for easier debugging.
Sources: src/helpers/Logger.ts:8-40, src/helpers/Logger.ts:90-99
Log Levels and Methods
The Logger class provides static methods for different log severities.
| Method | Description |
|---|---|
success() | Logs a success message (info level). |
log() | Standard informational logging. |
warn() | Logs a warning message. |
error() | Logs an error, sends a notification to the webhook, and reports the error to Honeybadger. |
debug() | Logs a debug-level message, typically used for verbose development output and not enabled in production. |
Sources: src/helpers/Logger.ts:102-127
Error Handling Flow
When Logger.error() is called, it triggers a specific sequence to ensure the error is captured and reported effectively.
This diagram shows the process flow when an error is logged.
Guild Event Logging
This system is designed for server administrators to monitor activity within their guild. It is highly configurable through the /logs command and its associated UI handlers.
Sources: src/handlers/admin/logging/index.ts, src/commands/admin/logs.ts
Configuration
Administrators can configure logging through an interactive menu system. The entry point is the /logs command, which displays the main logging configuration menu.
Sources: src/commands/admin/logs.ts:18-21, src/handlers/admin/logging/index.ts:172-189
Configurable Events
The system allows toggling logs for a wide variety of events, grouped into categories.
| Category | Event | Configuration Path |
|---|---|---|
| General | Master Switch | logs.enabled |
| Member | Message Edits | logs.member.message_edit |
| Message Deletes | logs.member.message_delete | |
| Role Changes | logs.member.role_changes | |
| Automod | Ghost Ping Detection | automod.anti_ghostping |
| Channel | Channel Created | logs.channel.create |
| Channel Updated | logs.channel.edit | |
| Channel Deleted | logs.channel.delete | |
| Role | Role Created | logs.role.create |
| Role Updated | logs.role.edit | |
| Role Deleted | logs.role.delete |
Sources: src/handlers/admin/logging/index.ts:43-66, src/handlers/admin/logging/index.ts:101-115
Configuration Flow
The following diagram illustrates the sequence of interactions when an admin configures a logging setting.
Event Handling
When a Discord event occurs (e.g., a message is deleted), the corresponding event handler is triggered. The handler first checks the guild's settings to see if logging for that event is enabled. If so, it constructs and sends an embed to the designated log channel.
The messageDelete event is a typical example of this flow.
Moderation Logging (ModLog)
Specific moderation actions, such as warnings, are persisted in the database using the ModLog schema. This creates a permanent audit trail for each user.
Sources: src/database/schemas/ModLog.ts, src/commands/moderation/warnings.ts
Data Schema
The mod-logs collection stores structured data about moderation actions.
This ER diagram shows the structure of the ModLog schema.
Sources: src/database/schemas/ModLog.ts:12-32
Schema Fields
| Field | Type | Description |
|---|---|---|
type | String | The type of moderation log (e.g., WARN, UNWARN). |
guildId | String | The ID of the guild where the action occurred. |
memberId | ObjectId | The ID of the user who was the subject of the action. |
adminId | ObjectId | The ID of the administrator who performed the action. |
reason | String | The reason for the moderation action. |
createdAt | Date | Timestamp of when the log entry was created. |
Sources: src/database/schemas/ModLog.ts:12-32
The /warnings list and /warnings clear commands directly interact with this schema to retrieve and manage a user's warning history.
Sources: src/commands/moderation/warnings.ts:100-123, src/commands/moderation/warnings.ts:125-149
Specialized Logging Systems
Automod Logging
The automod system logs its actions both to the database (automod-logs collection) and to the guild's configured log channel. When automod flags a message (e.g., for spam, mass mentions), it increments the user's strike count and creates a detailed log entry.
Sources: src/handlers/automod.ts:200-224
Report & Feedback Logging
The user report and feedback system operates independently of the guild log channel. It uses a dedicated Discord webhook, defined by FEEDBACK.URL in the configuration, to send all submissions to a private channel for developer review. This ensures that sensitive reports are handled discreetly.
Sources: src/handlers/report.ts:223-267, src/config/config.ts:40-43
Summary
Amina's logging system is a robust and flexible feature that serves two critical audiences. For developers, it provides detailed internal diagnostics, error reporting, and performance monitoring through pino, webhooks, and Honeybadger. For server administrators, it offers a powerful and granular audit trail for guild events and moderation actions, all manageable through an intuitive user interface. The separation of these concerns, combined with specialized logging for systems like automod and user reports, makes it a cornerstone of the bot's operational and administrative capabilities.