abrahammurciano / discord-lumberjack

A Python logging handler which sends its logs to a Discord Channel

discord-lumberjack

A Python logging handler which sends its logs to a Discord Channel or Webhook.

Documentation

You can find the documentation here.

Installation

To install this python module, run the following command

$ pip install discord-lumberjack

Handlers

This python module provides several logging handlers (located in the discord_lumberjack.handlers module) which will send the logs it recieves to a Discord webhook, server channel, or DM channel.

The available handlers are:

• DiscordChannelHandler - Uses a bot token and a channel ID to send logs to the given channel from the given bot.
• DiscordDMHandler - Uses a bot token and a user ID to send logs to the given user from the given bot.
• DiscordWebhookHandler - Uses a webhook URL to send the logs to.
• DiscordHandler - This is the base class for the other three. You probably don't want to use this unless you're creating your own fancy handler.

Message Creators

In order to send nice looking messages, there are a few message creators available (located in the discord_lumberjack.message_creators module). These are responsible for converting a logging.LogRecord into a message structure that will be sent to Discord's API.

The message creators provided currently will split extremely long messages into several in order to fit within Discord's message limits. If you decide to create your own one, keep that in mind too.

The available message creators are:

• BasicMessageCreator - This is a simple message creator which will use the handler's set formatter to send the message as plain text. By default, the message will be formatted in monospace, but this can be disabled via the constructor.
• EmbedMessageCreator - This message creator will create a fancy-looking embed message from the log record. It will ignore the handler's formatter.

Usage

The easiest way to get started is to create a webhook and use that, but if you're using this to log a Discord bot, you can use it's token directly, without needing to create webhooks.

Import

First, you should import the handlers you want to use. For this example, we'll assume we have a Discord bot and we'd like to use it to log every message to a channel and also to send errors to a DM.

We'll be using the DiscordChannelHandler to send all messages of level INFO and above to the channel and DiscordDMHandler to send messages of level ERROR and above to a DM.

from discord_lumberjack.handlers import DiscordChannelHandler, DiscordDMHandler

Basic Setup

You should really read the documentation for the logging module to learn how to set up your logging, but here's a quick snippet to get you started.

import logging
logging.basicConfig(
	level=logging.INFO,
	handlers=[
		DiscordChannelHandler(token=my_bot_token, channel_id=my_channel_id),
		DiscordDMHandler(token=my_bot_token, user_id=my_user_id, level=logging.ERROR),
	]
)

Once you've set up your logging, you can start logging messages like this:

logging.info("This is an informative message that will be sent to the channel.")
logging.error("This is an error, so it will also be sent to the DM.")

discord-lumberjack's Issues

Make sure that calls to log are quick

Should definitely never take 3 seconds. Probably 0.1s is even too long. Time it, figure out a reasonable limit, add a test to make sure it doesn't take longer than that.

Make sure embed sections are in the right order when split

E.g. description is after first part of title but should be after last

Allow user to choose the number of consumer threads that send messages to discord

If a user logs too often the queue will grow much faster than it can be dequeued. One possible solution is to use more consumer threads.

• check if more threads improves performance
• if so, add parameter for number of threads in DiscordHandler

Incompatible with Python<3.10

I am getting a stack trace when I try to import the latest version. Please see steps below to reproduce.

$ pip install discord-lumberjack
$ pip list | grep discord-lumberjack
discord-lumberjack 1.0.2

$ python
>>> import discord_lumberjack
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/root/.cache/pypoetry/virtualenvs/bobcat-miner-BajaH40D-py3.9/lib/python3.9/site-packages/discord_lumberjack/__init__.py", line 8, in <module>
    from . import handlers
  File "/root/.cache/pypoetry/virtualenvs/bobcat-miner-BajaH40D-py3.9/lib/python3.9/site-packages/discord_lumberjack/handlers/__init__.py", line 9, in <module>
    from .discord_handler import DiscordHandler
  File "/root/.cache/pypoetry/virtualenvs/bobcat-miner-BajaH40D-py3.9/lib/python3.9/site-packages/discord_lumberjack/handlers/discord_handler.py", line 6, in <module>
    from discord_lumberjack.message_creators import BasicMessageCreator, MessageCreator
  File "/root/.cache/pypoetry/virtualenvs/bobcat-miner-BajaH40D-py3.9/lib/python3.9/site-packages/discord_lumberjack/message_creators/__init__.py", line 11, in <module>
    from .embed_message_creator import EmbedMessageCreator
  File "/root/.cache/pypoetry/virtualenvs/bobcat-miner-BajaH40D-py3.9/lib/python3.9/site-packages/discord_lumberjack/message_creators/embed_message_creator.py", line 5, in <module>
    from .embed import Embed, EmbedFieldSetter, embed_length, empty_embed
  File "/root/.cache/pypoetry/virtualenvs/bobcat-miner-BajaH40D-py3.9/lib/python3.9/site-packages/discord_lumberjack/message_creators/embed.py", line 89, in <module>
    class EmbedFieldSetter:
  File "/root/.cache/pypoetry/virtualenvs/bobcat-miner-BajaH40D-py3.9/lib/python3.9/site-packages/discord_lumberjack/message_creators/embed.py", line 100, in EmbedFieldSetter
    key_chain: Sequence[str | int],
TypeError: unsupported operand type(s) for |: 'type' and 'type'
>>> import discord-lumberjack
KeyboardInterrupt

💥 💥 💥

Program exits and last logs are not sent to Discord

I have noticed some interesting behavior. if the program exits normally then the last last few log events are not sent to Discord. However, you if place a time.sleep(10) at the end, there is a better chance the logs are flushed and sent to Discord.

Use proper logging internally

Automatically bump version in master after publishing a version

Add test for custom embed creator

Allow choosing channel depending on log lever

Provide a way for the user to specify which channel to send logs to depending on the level of the log.

For example a user might have a channel for anything of level ERROR and above, in which they'll be notified for every message. They might also have a channel for WARNINGs which they won't be notified on but it might not necessarily be muted. Finally they might have a channel for DEBUG and INFO which will be muted and they'll only check it when they're looking for something specific.

Note that levels are really just integers, and users are allowed to specify their own, so the solution to this should take that into consideration

Make wait exponential for rate limit

Wait first 0.1, then 0.2, then 0.4, etc before retrying to send a rate limited message

Infinite recursion if discord handler handles itself (including root logger)

Issue warning when queue gets too full

Ideas/To do

• Add parameter queue_warning_size (default 100?)
• Replace Queue with a priority queue
• Issue queue size warnings with higher priority
• Make sure queue size warning is not issued too frequently
  • Maybe only once
  • Maybe once per queue fill up (e.g. once it gets full and a warning is issued, it won't be issued again until queue is half empty then fills up again)
    • bool issue_warning (init True) set to false after warning is issued and set to true when dequeueing and qsize() < queue_warning_size/2
    • when emitting, if qsize() > queue_warning_size and issue_warning, then enqueue log record with higher priority and set issue_warning to False

Discord message are not rendered

description

The message sent to discord are not being render.

• This means we cannot colorize messages based on log level e.g. yellow for warning or red for error/critical.

• Being able to use mentions would be really powerful because an operate could add a mention to an error log msg and then they would get a notification in the Discord app.

expected behavior

# https://hackernoon.com/sending-events-and-logs-to-discord-via-python
import requests
import os

discord_webhook_url = os.getenv("DISCORD_WEBHOOK_URL")
requests.post(discord_webhook_url, { "content": "Helloworld 👋" })
requests.post(discord_webhook_url, { "content": "```fix\nThis is be yellow\n```" })
requests.post(discord_webhook_url, { "content": "@everyone there was an alert. get a notification" })

result:

actual behavior

from discord_lumberjack.handlers import DiscordWebhookHandler
import logging
import os

discord_webhook_url = os.getenv("DISCORD_WEBHOOK_URL")
logger = logging.getLogger()
logger.setLevel(logging.INFO)
logger.addHandler(DiscordWebhookHandler(url=discord_webhook_url))
logger.info("Helloworld 👋")
logger.warning("```fix\nThis is be yellow\n```")
logger.error("@everyone there was an alert. get a notification")

result:

Write tutorials in the github wiki

• write a more in depth tutorial on getting started
• write a tutorial on subclassing EmbedMessageCreator