# Python Discord Logger
A custom message logger to Discord for Python 3.
This project was inspired from [`winston-discord-transport`](https://github.com/sidhantpanda/winston-discord-transport) for NodeJS
and built using [discord-webhook](https://github.com/lovvskillz/python-discord-webhook), which offers an easy interface for
constructing and sending messages through a Discord webhook.
If you are looking for a Slack alternative, please check [python-slack-logger](https://github.com/chinnichaitanya/python-slack-logger).
<a href="https://pypi.org/project/discord-logger/"><img alt="PyPI - Python Version" src="https://img.shields.io/pypi/pyversions/discord-logger"></a>
[](https://badge.fury.io/py/discord-logger)
<a href="https://pepy.tech/project/discord-logger"><img alt="Downloads" src="https://static.pepy.tech/badge/discord-logger"></a>
<a href="https://pypi.org/project/discord-logger/#files"><img alt="PyPI - Wheel" src="https://img.shields.io/pypi/wheel/discord-logger"></a>
[](https://github.com/chinnichaitanya/python-discord-logger/blob/master/LICENSE)
[](https://github.com/python/black)
## Install
Install via pip: `pip install discord-logger`
## Basic Usage
```python
from discord_logger import DiscordLogger
options = {
"application_name": "My Server",
"service_name": "Backend API",
"service_icon_url": "your icon url",
"service_environment": "Production",
"display_hostname": True,
"default_level": "info",
}
logger = DiscordLogger(webhook_url="your discord webhook url", **options)
logger.construct(title="Health Check", description="All services are running normally!")
response = logger.send()
```
## Configure various options
There are numerous configurations available to customise the bot.
```python
options = {
# Application name would replace the webhook name set during creating of the webhook
# It would appear as the name of the bot
# If unset, the default value would be "Application"
"application_name": "My Server",
# Service name would be the name of the service sending the message to your Discord channel
# This would usually be the name of the application sending the notification
# If unset, the default value would be "Status Bot"
"service_name": "Backend API",
# Service icon URL is the icon image for your application
# This field accepts a URL to the icon image
# If unspecified, the icon wouldn't be set
# If misconfigured, the icon wouldn't load and a blank space would appear before the service name
"service_icon_url": "your icon url",
# Usually services would run in staging and production environments
# This field is to specify the environment from which the application is reponding for easy identification
# If unset, this block would not appear in the message
"service_environment": "Production",
# An option to specify whether or not to display the hostname in the messages
# The hostname is set by default, but it could be disabled by specifically setting this to `False`
"display_hostname": True,
# The default importance level of the message
# The left bar color of the message would change depending on this
# Available options are
# - default: 2040357
# - error: 14362664
# - warn: 16497928
# - info: 2196944
# - verbose: 6559689
# - debug: 2196944
# - success: 2210373
# If the `error` field is set during the construction of the message, the `level` is automatically set to `error`
# If nothing is specified, `default` color would be used
"default_level": "info",
# specify proxies to use, default is None
proxies = {
'http': 'http://10.10.1.10:3128',
'https': 'http://10.10.1.10:1080',
}
}
```
## Emojis inbuilt! 😃
An appropriate emoji is automatically added before the title depending on the `level`.
Following is the map between `level` and the emoji added.
- default = `:loudspeaker:` 📢
- error = `:x:` ❌
- warn = `:warning:` ⚠️
- info = `:bell:` 🔔
- verbose = `:mega:` 📣
- debug = `:microscope:` 🔬
- success = `:rocket:` 🚀
## Examples
### Set Service Name, Icon and Environment for easy identification
You can configure the log message with service name, icon and environment for easy identification. The `Host` field which is the hostname of the server is automatically added for every message.
You can even send any meta information like the data in the variables, module names, metrics etc with the `metadata` field while constructing the message.
These data should be passed as a dictionary.
```python
from discord_logger import DiscordLogger
webhook_url = "your discord webhook url"
options = {
"application_name": "My Server",
"service_name": "Backend API",
"service_icon_url": "your icon url",
"service_environment": "Production",
"default_level": "info",
}
logger = DiscordLogger(webhook_url=webhook_url, **options)
logger.construct(
title="Health Check",
description="Issue in establishing DB connections!",
error="Traceback (most recent call last):\n ValueError: Database connect accepts only string as a parameter!",
metadata={"module": "DBConnector", "host": 123.332},
)
response = logger.send()
```
### Send messages without Hostname
In case you do not want the hostname to be displayed in the message, disable it by setting `"display_hostname": False` in the `options` as follows.
```python
from discord_logger import DiscordLogger
webhook_url = "your discord webhook url"
options = {
"application_name": "My Server",
"service_name": "Backend API",
"service_icon_url": "your icon url",
"service_environment": "Production",
"default_level": "info",
"display_hostname": False,
}
logger = DiscordLogger(webhook_url=webhook_url, **options)
logger.construct(title="Health Check", description="All services are running normally!")
response = logger.send()
```
### Send messages with different log-levels
The log-level indicates the importance of the message. It changes the color of the discord message in particular. Currently supported levels are,
- `error`
- `warn`
- `info`
- `verbose`
- `debug`
- `success`
The log-level can be set during construction of the message like through the parameter `level`.
If the parameter isn't provided, it'll be set to the one given in `default_level`. Any invalid input would be ignored and the log-level would be automatically be set to `default`.
Any complicated nested dictionary can be passed to the `metadata` field and the message gets forrmatted accordingly for easy reading.
```python
from discord_logger import DiscordLogger
webhook_url = "your discord webhook url"
options = {
"application_name": "My Server",
"service_name": "Backend API",
"service_icon_url": "your icon url",
"service_environment": "Production",
"default_level": "info",
}
logger = DiscordLogger(webhook_url=webhook_url, **options)
logger.construct(
title="Celery Task Manager",
description="Successfully completed training job for model v1.3.3!",
level="success",
metadata={
"Metrics": {
"Accuracy": 78.9,
"Inference time": "0.8 sec",
"Model size": "32 MB",
},
"Deployment status": "progress",
},
)
response = logger.send()
```
### Send complete error traceback
The `error` field can contain any error message. It will be automatically be formatted in the final message. For example, you can send a complete traceback of an error message to debug faster!
```python
import traceback
from discord_logger import DiscordLogger
def get_traceback(e):
tb = (
"Traceback (most recent call last):\n"
+ "".join(traceback.format_list(traceback.extract_tb(e.__traceback__)))
+ type(e).__name__
+ ": "
+ str(e)
)
return tb
webhook_url = "your discord webhook url"
options = {
"application_name": "My Server",
"service_name": "Backend API",
"service_icon_url": "your icon url",
"service_environment": "Production",
"default_level": "info",
}
err = KeyError("`email` field cannot be None")
logger = DiscordLogger(webhook_url=webhook_url, **options)
logger.construct(
title="Runtime Exception",
description=err.__str__(),
error=get_traceback(err),
metadata={"email": None, "module": "auth", "method": "POST"},
)
response = logger.send()
```
Raw data
{
"_id": null,
"home_page": "https://github.com/iamtalhaasghar/python-discord-logger",
"name": "discord-logger-ng",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.5",
"maintainer_email": null,
"keywords": "monitoring, discord, messaging, logging, health-check, notification-service, notification, discord-webhook",
"author": "Talha Asghar",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/4f/fa/8ec2874ac3e09e9d1dfe0127d9e6190dbf6566a4c2310b41582c1a75dad5/discord_logger_ng-1.2.4.tar.gz",
"platform": null,
"description": "# Python Discord Logger\n\nA custom message logger to Discord for Python 3.\nThis project was inspired from [`winston-discord-transport`](https://github.com/sidhantpanda/winston-discord-transport) for NodeJS\nand built using [discord-webhook](https://github.com/lovvskillz/python-discord-webhook), which offers an easy interface for\nconstructing and sending messages through a Discord webhook.\n\nIf you are looking for a Slack alternative, please check [python-slack-logger](https://github.com/chinnichaitanya/python-slack-logger).\n\n<a href=\"https://pypi.org/project/discord-logger/\"><img alt=\"PyPI - Python Version\" src=\"https://img.shields.io/pypi/pyversions/discord-logger\"></a>\n[](https://badge.fury.io/py/discord-logger)\n<a href=\"https://pepy.tech/project/discord-logger\"><img alt=\"Downloads\" src=\"https://static.pepy.tech/badge/discord-logger\"></a>\n<a href=\"https://pypi.org/project/discord-logger/#files\"><img alt=\"PyPI - Wheel\" src=\"https://img.shields.io/pypi/wheel/discord-logger\"></a>\n[](https://github.com/chinnichaitanya/python-discord-logger/blob/master/LICENSE)\n[](https://github.com/python/black)\n\n## Install\n\nInstall via pip: `pip install discord-logger`\n\n## Basic Usage\n\n```python\nfrom discord_logger import DiscordLogger\n\noptions = {\n \"application_name\": \"My Server\",\n \"service_name\": \"Backend API\",\n \"service_icon_url\": \"your icon url\",\n \"service_environment\": \"Production\",\n \"display_hostname\": True,\n \"default_level\": \"info\",\n}\n\nlogger = DiscordLogger(webhook_url=\"your discord webhook url\", **options)\nlogger.construct(title=\"Health Check\", description=\"All services are running normally!\")\n\nresponse = logger.send()\n```\n\n![Image](https://raw.githubusercontent.com/chinnichaitanya/python-discord-logger/master/images/basic_message.png \"Basic Usage\")\n\n## Configure various options\n\nThere are numerous configurations available to customise the bot.\n\n```python\noptions = {\n # Application name would replace the webhook name set during creating of the webhook\n # It would appear as the name of the bot\n # If unset, the default value would be \"Application\"\n \"application_name\": \"My Server\",\n\n # Service name would be the name of the service sending the message to your Discord channel\n # This would usually be the name of the application sending the notification\n # If unset, the default value would be \"Status Bot\"\n \"service_name\": \"Backend API\",\n\n # Service icon URL is the icon image for your application\n # This field accepts a URL to the icon image\n # If unspecified, the icon wouldn't be set\n # If misconfigured, the icon wouldn't load and a blank space would appear before the service name\n \"service_icon_url\": \"your icon url\",\n\n # Usually services would run in staging and production environments\n # This field is to specify the environment from which the application is reponding for easy identification\n # If unset, this block would not appear in the message\n \"service_environment\": \"Production\",\n\n # An option to specify whether or not to display the hostname in the messages\n # The hostname is set by default, but it could be disabled by specifically setting this to `False`\n \"display_hostname\": True,\n\n # The default importance level of the message\n # The left bar color of the message would change depending on this\n # Available options are\n # - default: 2040357\n # - error: 14362664\n # - warn: 16497928\n # - info: 2196944\n # - verbose: 6559689\n # - debug: 2196944\n # - success: 2210373\n # If the `error` field is set during the construction of the message, the `level` is automatically set to `error`\n # If nothing is specified, `default` color would be used\n \"default_level\": \"info\",\n \n # specify proxies to use, default is None\n proxies = {\n 'http': 'http://10.10.1.10:3128',\n 'https': 'http://10.10.1.10:1080',\n }\n}\n```\n\n## Emojis inbuilt! \ud83d\ude03\n\nAn appropriate emoji is automatically added before the title depending on the `level`.\n\nFollowing is the map between `level` and the emoji added.\n\n- default = `:loudspeaker:` \ud83d\udce2\n- error = `:x:` \u274c\n- warn = `:warning:` \u26a0\ufe0f\n- info = `:bell:` \ud83d\udd14\n- verbose = `:mega:` \ud83d\udce3\n- debug = `:microscope:` \ud83d\udd2c\n- success = `:rocket:` \ud83d\ude80\n\n## Examples\n\n### Set Service Name, Icon and Environment for easy identification\n\nYou can configure the log message with service name, icon and environment for easy identification. The `Host` field which is the hostname of the server is automatically added for every message.\n\nYou can even send any meta information like the data in the variables, module names, metrics etc with the `metadata` field while constructing the message.\nThese data should be passed as a dictionary.\n\n```python\nfrom discord_logger import DiscordLogger\n\nwebhook_url = \"your discord webhook url\"\noptions = {\n \"application_name\": \"My Server\",\n \"service_name\": \"Backend API\",\n \"service_icon_url\": \"your icon url\",\n \"service_environment\": \"Production\",\n \"default_level\": \"info\",\n}\n\nlogger = DiscordLogger(webhook_url=webhook_url, **options)\nlogger.construct(\n title=\"Health Check\",\n description=\"Issue in establishing DB connections!\",\n error=\"Traceback (most recent call last):\\n ValueError: Database connect accepts only string as a parameter!\",\n metadata={\"module\": \"DBConnector\", \"host\": 123.332},\n)\n\nresponse = logger.send()\n```\n\n![Image](https://raw.githubusercontent.com/chinnichaitanya/python-discord-logger/master/images/error_message.png \"Message with Service Name, Icon and Environment\")\n\n### Send messages without Hostname\n\nIn case you do not want the hostname to be displayed in the message, disable it by setting `\"display_hostname\": False` in the `options` as follows.\n\n```python\nfrom discord_logger import DiscordLogger\n\nwebhook_url = \"your discord webhook url\"\noptions = {\n \"application_name\": \"My Server\",\n \"service_name\": \"Backend API\",\n \"service_icon_url\": \"your icon url\",\n \"service_environment\": \"Production\",\n \"default_level\": \"info\",\n \"display_hostname\": False,\n}\n\nlogger = DiscordLogger(webhook_url=webhook_url, **options)\nlogger.construct(title=\"Health Check\", description=\"All services are running normally!\")\n\nresponse = logger.send()\n```\n\n![Image](https://raw.githubusercontent.com/chinnichaitanya/python-discord-logger/master/images/basic_message_without_hostname.png \"Basic message without Hostname\")\n\n### Send messages with different log-levels\n\nThe log-level indicates the importance of the message. It changes the color of the discord message in particular. Currently supported levels are,\n\n- `error`\n- `warn`\n- `info`\n- `verbose`\n- `debug`\n- `success`\n\nThe log-level can be set during construction of the message like through the parameter `level`.\n\nIf the parameter isn't provided, it'll be set to the one given in `default_level`. Any invalid input would be ignored and the log-level would be automatically be set to `default`.\n\nAny complicated nested dictionary can be passed to the `metadata` field and the message gets forrmatted accordingly for easy reading.\n\n```python\nfrom discord_logger import DiscordLogger\n\nwebhook_url = \"your discord webhook url\"\noptions = {\n \"application_name\": \"My Server\",\n \"service_name\": \"Backend API\",\n \"service_icon_url\": \"your icon url\",\n \"service_environment\": \"Production\",\n \"default_level\": \"info\",\n}\n\nlogger = DiscordLogger(webhook_url=webhook_url, **options)\nlogger.construct(\n title=\"Celery Task Manager\",\n description=\"Successfully completed training job for model v1.3.3!\",\n level=\"success\",\n metadata={\n \"Metrics\": {\n \"Accuracy\": 78.9,\n \"Inference time\": \"0.8 sec\",\n \"Model size\": \"32 MB\",\n },\n \"Deployment status\": \"progress\",\n },\n)\n\nresponse = logger.send()\n```\n\n![Image](https://raw.githubusercontent.com/chinnichaitanya/python-discord-logger/master/images/success_message.png \"Message with success log-level\")\n\n### Send complete error traceback\n\nThe `error` field can contain any error message. It will be automatically be formatted in the final message. For example, you can send a complete traceback of an error message to debug faster!\n\n```python\nimport traceback\n\nfrom discord_logger import DiscordLogger\n\n\ndef get_traceback(e):\n tb = (\n \"Traceback (most recent call last):\\n\"\n + \"\".join(traceback.format_list(traceback.extract_tb(e.__traceback__)))\n + type(e).__name__\n + \": \"\n + str(e)\n )\n return tb\n\n\nwebhook_url = \"your discord webhook url\"\noptions = {\n \"application_name\": \"My Server\",\n \"service_name\": \"Backend API\",\n \"service_icon_url\": \"your icon url\",\n \"service_environment\": \"Production\",\n \"default_level\": \"info\",\n}\n\nerr = KeyError(\"`email` field cannot be None\")\n\nlogger = DiscordLogger(webhook_url=webhook_url, **options)\nlogger.construct(\n title=\"Runtime Exception\",\n description=err.__str__(),\n error=get_traceback(err),\n metadata={\"email\": None, \"module\": \"auth\", \"method\": \"POST\"},\n)\n\nresponse = logger.send()\n```\n\n![Image](https://raw.githubusercontent.com/chinnichaitanya/python-discord-logger/master/images/complete_error_traceback.png \"Message with complete error traceback\")\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "Discord Logger is a custom message logger to Discord for Python 3 with proxy and user / role mentions support.",
"version": "1.2.4",
"project_urls": {
"Homepage": "https://github.com/iamtalhaasghar/python-discord-logger"
},
"split_keywords": [
"monitoring",
" discord",
" messaging",
" logging",
" health-check",
" notification-service",
" notification",
" discord-webhook"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "623f35b9499fa4c460464f1d8cbf30f5ef888a9ff1d7813db04a5c1454cf1948",
"md5": "105b8e922f165f4a4d6209dcbd5e7030",
"sha256": "5cebd1e29775e80760cb4ccaf31aca59954dd719f56d1c5abf8cb55f50e9db25"
},
"downloads": -1,
"filename": "discord_logger_ng-1.2.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "105b8e922f165f4a4d6209dcbd5e7030",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.5",
"size": 9766,
"upload_time": "2024-09-10T10:52:49",
"upload_time_iso_8601": "2024-09-10T10:52:49.322078Z",
"url": "https://files.pythonhosted.org/packages/62/3f/35b9499fa4c460464f1d8cbf30f5ef888a9ff1d7813db04a5c1454cf1948/discord_logger_ng-1.2.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "4ffa8ec2874ac3e09e9d1dfe0127d9e6190dbf6566a4c2310b41582c1a75dad5",
"md5": "377920363c90a735d9ac254a87d55491",
"sha256": "9f17f406cf8fbf8c422c574cdbb4c2f036013df837dd41ba02756faf16cf91b5"
},
"downloads": -1,
"filename": "discord_logger_ng-1.2.4.tar.gz",
"has_sig": false,
"md5_digest": "377920363c90a735d9ac254a87d55491",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.5",
"size": 7573,
"upload_time": "2024-09-10T10:52:51",
"upload_time_iso_8601": "2024-09-10T10:52:51.215396Z",
"url": "https://files.pythonhosted.org/packages/4f/fa/8ec2874ac3e09e9d1dfe0127d9e6190dbf6566a4c2310b41582c1a75dad5/discord_logger_ng-1.2.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-10 10:52:51",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "iamtalhaasghar",
"github_project": "python-discord-logger",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "discord-logger-ng"
}
JSON
