{"id":27874268,"url":"https://github.com/ixe1/loggerhead","last_synced_at":"2026-04-29T10:04:53.736Z","repository":{"id":230594972,"uuid":"779745439","full_name":"Ixe1/loggerhead","owner":"Ixe1","description":"A Discord bot that logs various events and activities in your Discord server.","archived":false,"fork":false,"pushed_at":"2024-04-01T21:05:04.000Z","size":39,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-05T01:37:10.776Z","etag":null,"topics":["discord","discord-bot","logger","logging"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Ixe1.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2024-03-30T17:02:32.000Z","updated_at":"2024-03-30T17:15:38.000Z","dependencies_parsed_at":"2024-03-31T18:49:08.721Z","dependency_job_id":null,"html_url":"https://github.com/Ixe1/loggerhead","commit_stats":null,"previous_names":["ixe1/loggerhead"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Ixe1/loggerhead","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ixe1%2Floggerhead","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ixe1%2Floggerhead/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ixe1%2Floggerhead/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ixe1%2Floggerhead/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Ixe1","download_url":"https://codeload.github.com/Ixe1/loggerhead/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ixe1%2Floggerhead/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259352987,"owners_count":22844746,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["discord","discord-bot","logger","logging"],"created_at":"2025-05-05T01:32:12.345Z","updated_at":"2026-04-29T10:04:53.702Z","avatar_url":"https://github.com/Ixe1.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# LoggerHead\n\nA Discord bot that logs various events and activities in your Discord server.\n\n## Features\n\n- Logs a wide range of events, including:\n  - Channel creation, deletion, and updates\n  - Role creation, deletion, and updates\n  - Server updates\n  - Invite creation and deletion\n  - Member join, leave, ban, kick, timeout, and updates\n  - Message deletion and editing\n  - Reaction addition and removal\n  - Voice channel activity\n  - Webhook updates\n- Configurable logging channel and events to log for each server\n- Batching of log messages for busy servers to avoid hitting rate limits\n- Dynamic batching threshold based on server activity\n- Periodic reporting of requests per second to monitor bot activity\n- Supports multiple Discord servers, with the configuration for each server being stored in a PostgreSQL database\n\n## Planned\n\n- Caching of Discord messages to PostgresSQL database\n  - This means if the bot is restarted then it still has a recollection of a certain number of chat messages per guild (Discord server)\n- Refactoring\n  - Yeah, I know, the code is probably not that tidy at the moment\n\n## Installation\n\n1. Clone the repository:\n\n`git clone https://github.com/Ixe1/loggerhead.git`\n\n2. Install the required dependencies:\n\n`pip install -r requirements.txt`\n\n3. Set up the configuration:\n   - Create a `config.yaml` file in the project directory with the following structure:\n\n```yaml\ndiscord_token: \"YOUR_DISCORD_BOT_TOKEN\"\ndb_host: \"YOUR_DATABASE_HOST\"\ndb_user: \"YOUR_DATABASE_USER\"\ndb_password: \"YOUR_DATABASE_PASSWORD\"\ndb_name: \"YOUR_DATABASE_NAME\"\n```\n\n   - Replace the placeholders with your actual Discord bot token and database connection details.\n\n4. Run the bot:\n\n`python main.py`\n\n## Usage\n\n1. Invite the bot to your Discord server using the bot invite link.\n\n2. Set the logging configuration using the following commands:\n   - `!setlogconfig \u003clog_channel\u003e \u003clog_events\u003e`: Set the logging channel and events to log (comma-separated)\n   - `!getlogconfig`: Get the current logging configuration\n   - `!loghelp`: Display the list of available commands and configurable events\n\n   Example: `!setlogconfig #log-channel member_join,member_leave,message_delete`\n\n3. The bot will start logging the configured events in the designated logging channel.\n\n4. By default, all events are enabled for logging. You can customize the events to log using the `!setlogconfig` command.\n\n## Configurable Events\n\nThe following events can be configured for logging:\n\n- `guild_channel_create`: Channel creation\n- `guild_channel_delete`: Channel deletion\n- `guild_channel_update`: Channel updates\n- `guild_emojis_update`: Emoji updates\n- `guild_role_create`: Role creation\n- `guild_role_delete`: Role deletion\n- `guild_role_update`: Role updates\n- `guild_update`: Server updates\n- `invite_create`: Invite creation\n- `invite_delete`: Invite deletion\n- `member_join`: Member join\n- `member_remove`: Member leave\n- `message_delete`: Message deletion\n- `message_edit`: Message editing\n- `member_ban`: Member ban\n- `member_kick`: Member kick\n- `member_remove_timeout`: Member timeout removal\n- `member_timeout`: Member timeout\n- `member_unban`: Member unban\n- `member_update`: Member updates\n- `reaction_add`: Reaction addition\n- `reaction_remove`: Reaction removal\n- `voice_state_update`: Voice channel activity\n- `webhooks_update`: Webhook updates\n\n## Database Configuration\n\nThe bot uses a PostgreSQL database to store the logging configuration for each server. Make sure to set up the database and provide the necessary connection details in the `config.yaml` file.\n\nThe bot will automatically create the required tables if they don't exist.\n\n## Permissions\n\nThe bot requires the following permissions:\n\n- View Channels\n- Send Messages\n- Embed Links\n- Read Message History\n- View Audit Log\n- Manage Server (for invite tracking)\n- Manage Webhooks\n\nMake sure to grant the bot these permissions when inviting it to your server.\n\n## Logging\n\nThe bot uses the `logging` module to log important information and errors. The log messages are displayed in the console.\n\n## Rate Limiting\n\nThe bot handles rate limiting when sending log messages to avoid exceeding Discord's rate limits. It uses the `RateLimitedWebhook` class to handle rate limiting and retrying failed requests.\n\n## Contributing\n\nContributions to the project are welcome! If you find any bugs, have feature requests, or want to contribute improvements, please submit an issue or a pull request on the GitHub repository.\n\nTo set up the development environment:\n1. Clone the repository\n2. Install the required dependencies\n3. Set up the `config.yaml` file with your bot token and database connection details\n4. Run the bot using `python main.py`\n\n## Troubleshooting\n\n- If the bot fails to connect to the database, make sure the database connection details in the `config.yaml` file are correct and the database is running.\n- If the bot encounters any errors or issues, check the console output for error messages and refer to the logs for more details.\n- If you encounter any other problems or have questions, please submit an issue on the GitHub repository.\n\n## License\n\nThis project is licensed under the [GNU Affero General Public License v3.0](LICENSE).","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fixe1%2Floggerhead","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fixe1%2Floggerhead","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fixe1%2Floggerhead/lists"}