About

This project provides a production-grade Telegram destination for Python's standard logging module. It allows you to send logs directly to a Telegram chat asynchronously, ensuring that your application's performance is not impacted by slow or unavailable Telegram Bot API responses. The handler includes robust features such as batching of logs, retries with exponential backoff, handling of rate limits (429 errors), splitting of oversized messages, back-pressure management for bounded queues, and automatic escaping of content for Telegram's formatting modes (MarkdownV2 or HTML).

Key Features

• Non-blocking Operation: Logs are processed in a separate thread, preventing the Telegram API from blocking your application's main execution flow.
• Error Resilience: Network and API errors are handled with retries and do not crash your application. Failed messages are reported to stderr.
• No Logging Recursion: Internal errors are sent to stderr, avoiding infinite logging loops.
• Configurable Batching: Logs can be batched into single messages to optimize API usage and stay within rate limits.
• Flexible Configuration: Supports environment variables and explicit parameter passing for token and chat ID. Offers various options for message overflow handling, parse modes, queue sizes, and shutdown timeouts.
• Rich Formatting Support: Properly escapes log content for use with Telegram's MarkdownV2 or HTML parse modes.
• Development Tools: Includes support for development workflows with tools like uv, pytest, ruff, and mypy.

Installation

Install the package using pip:

pip install tg-logging-handler

Requires Python 3.10+.

Usage

Integrate the handler into your Python logging configuration:

import logging from tg_logging_handler import TelegramLoggingHandler # Reads TG_TOKEN / TG_CHAT_ID from the environment. logging.getLogger().addHandler(TelegramLoggingHandler()) logging.error('Something broke') # delivered to your Telegram chat