Discord handler for Python logging framework
Project description
Python logging handler for Discord
Redirect your Python log output to Discord using Python logging subsystem and Discord Webhook library.
Use cases
- Easily share logs with non-technical colleagues
- Get notified on server-side errors
- Follow your batch job processes easily
- Good for businesses and communities that have their messaging set up in Discord
Features
- Minimum or no changes to a Python application needed
- Optional color coding of messages using Discord embeds
- Optional emoticons on messages using Unicode
- Discord rate limiting friendly for burst of logs
- Documentation
- Special handling for long log messages like tracebacks to deal with Discord's 2000 character max message length
Requirements
- Python 3.8+
Installation
pip install python-logging-discord-handler
poetry add python-logging-discord-handler
Usage
This example logs both to Discord and standard output.
First you need to
import logging
from discord_logging.handler import DiscordHandler
# See instructions below how to get a Webhook URL
webhook_url = # ...
logger = logging.getLogger()
stream_format = logging.Formatter("%(asctime)s - %(name)s - %(levelname)s - %(message)s")
discord_format = logging.Formatter("%(message)s")
discord_handler = DiscordHandler(
"Hello World Bot",
webhook_url,
avatar_url="https://i0.wp.com/www.theterminatorfans.com/wp-content/uploads/2012/09/the-terminator3.jpg?resize=900%2C450&ssl=1")
#discord_handler = DiscordHandler("Happy Bot", webhook_url, emojis={})
discord_handler.setFormatter(discord_format)
stream_handler = logging.StreamHandler()
stream_handler.setFormatter(stream_format)
# Add the handlers to the Logger
logger.addHandler(discord_handler)
logger.addHandler(stream_handler)
logger.setLevel(logging.DEBUG)
logger.info("This is an info message")
logger.debug("A debug message - usually not that interesting")
logger.error("Very nasty error messgae!")
Find more examples in the examples.py source code.
How to get Discord webhook URL
- Go to Edit channel (gear) in Discord
- Choose Integrations
- Choose View webhooks -> New
- Copy URL
Webhook URL security
It is recommend that you store the webhook URL outside your source code to avoid damage in hacks or similar security incidents.
In Linux/macOS shell you can do on the command line:
export DISCORD_TEST_WEBHOOK_URL=<your webhook URL here>
For long term configuration, you can create a file storing environment variables outside your source code tree, like in your home directory. Store the export
commands there.
# Text editor for a secrets.env file in your home directory on Linux
nano ~/secrets.env
In your Linux shell session, you can then read this file and make environment variables effective using source command in your shell:
# Reads secrets.env and executes all commands there and makes them effective
# in the current shell session
source ~/secrets.env
Then you can read the environment variable in your Python code:
import os
webhook_url = os.environ["DISCORD_TEST_WEBHOOK_URL"]
Discord limitations
- Max 2000 characters per message. See API documentation how to work around this limitation with different options. By default the bottom most lines of the log message, like a traceback, are shown.
- Discord embeds, those that give you a logging level color bar on the left, have very hard time to deal with long lines. Embeds are disabled for long lines by default.
Log output formatting logic
The log message are converted to Discord embeds with the following logic
- Single line log messsages are converted to embed titles
- For multi line log messages, the first line is the embed title and the following lines are the embed description
- Long lines or long messages cannot be convert to embeds, instead they use Discord Markdown code formattiong to preserve the readability of the output
- A special
message_break_char
can be assigned to manually split long messages
Colours and emoticons
Logging messages can be decorated with colours and emoticons.
Here are the defaults:
#: The default log level colors as hexacimal, converted int
DEFAULT_COLOURS = {
None: 2040357, # Unknown log level
logging.CRITICAL: 14362664, # Red
logging.ERROR: 14362664, # Red
logging.WARNING: 16497928, # Yellow
logging.INFO: 2196944, # Blue
logging.DEBUG: 8947848, # Gray
}
#: The default log emojis as
DEFAULT_EMOJIS = {
None: "", # Unknown log level
logging.CRITICAL: "🆘",
logging.ERROR: "❌",
logging.WARNING: "⚠️",
logging.INFO: "",
logging.DEBUG: "",
}
Emoticons are disabled by default as they often make the output a bit too colourful and harder to read.
Testing and development
Manual tests
Inspect how logging output looks in Discord.
- Checkout this Git repository
- Set up a dummy Discord channel
- Get its webhook URL
poetry install -E docs
export DISCORD_TEST_WEBHOOK_URL=...
python discord_logging/examples.py
This will dump some messages to your Discord.
Automated tests
Run:
pytest
History
Originally created for Trading Strategy to follow trading bot activity.
License
MIT
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for python_logging_discord_handler-0.1.4.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 8bfa839b6503b3b87e5851dd13bc5ff80bf2fadb496ac22c338ac10bd926f75a |
|
MD5 | 24af6e8c6b7229fdb3b47f03b53322c9 |
|
BLAKE2b-256 | a294c67d7d1bd268ed3f3dd6775905ea8523ef38a6ecd599d563367e947e75fb |
Hashes for python_logging_discord_handler-0.1.4-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | b804b48e3f5af8c9c781a9afe8243c806f01521662e38a60fcda2c3631d27f4f |
|
MD5 | 5e0f490ccb98c5022b398458a6f2c369 |
|
BLAKE2b-256 | d179669464da149b3a3b15b4f0d17e5ebd548d44c466b644a7b610ebf4987092 |