easy-tg-logger 0.1.0__tar.gz

easy_tg_logger-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2011-2025 The Bootstrap Authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

easy_tg_logger-0.1.0/PKG-INFO

@@ -0,0 +1,111 @@
+Metadata-Version: 2.4
+Name: easy_tg_logger
+Version: 0.1.0
+Summary: Minimal Python logger with Telegram notifications
+Author: Beltrán Offerrall
+Project-URL: Homepage, https://github.com/offerrall/py-telegram-logger
+Project-URL: Repository, https://github.com/offerrall/py-telegram-logger
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# easy_tg_logger
+
+[![PyPI version](https://img.shields.io/pypi/v/easy_tg_logger.svg)](https://pypi.org/project/easy_tg_logger/)
+[![Python](https://img.shields.io/pypi/pyversions/easy_tg_logger.svg)](https://pypi.org/project/easy_tg_logger/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+Fast, minimal async logger for local files with optional Telegram alerts. **Zero dependencies** (stdlib only).
+
+## Install
+
+```bash
+pip install easy_tg_logger
+```
+
+## Usage
+
+```python
+from pytelegram_logger import init_telegram_logger, log, shutdown_logger
+
+init_telegram_logger(name="my_app")
+
+log("App started")
+log("Database error", is_error=True)
+
+shutdown_logger()  # optional, flushes pending logs
+```
+
+### With Telegram alerts
+
+```python
+init_telegram_logger(
+    name="my_app",
+    telegram_token_logs="BOT_TOKEN_1",     # routine logs
+    telegram_token_errors="BOT_TOKEN_2",   # error alerts
+    telegram_chat_ids=["-1001234567890"],
+)
+
+log("Payment received", send_telegram=True)
+log("Critical failure", is_error=True, send_telegram=True)
+```
+
+Two tokens = two channels: routine logs stay separate from high-priority error alerts.
+
+## API
+
+### `init_telegram_logger(name, ...)`
+
+| Argument | Default | Description |
+|---|---|---|
+| `name` | — | **Required.** Unique instance id (e.g. `"api"`, `"worker_1"`). |
+| `log_dir` | `"logs"` | Directory for log files. |
+| `telegram_token_logs` | `None` | Bot token for routine logs. |
+| `telegram_token_errors` | `None` | Bot token for errors. |
+| `telegram_chat_ids` | `[]` | List of chat IDs. |
+| `retention_days` | `30` | Auto-delete files older than N days. |
+| `queue_maxsize` | `10000` | Max pending messages per queue. |
+
+### `log(message, is_error=False, send_telegram=False, save=True)`
+
+- `is_error=True` → error file + error token
+- `send_telegram=True` → also send to Telegram
+- `save=False` → Telegram only, no file
+
+### `shutdown_logger()`
+
+Graceful shutdown: drains queues and closes files. Optional but recommended.
+
+### `get_dropped_count(sink=None)`
+
+Messages dropped because a queue was full (logging never blocks the caller).
+
+```python
+get_dropped_count()            # total (disk + Telegram)
+get_dropped_count("file")      # local logs lost  ← the one that matters
+get_dropped_count("telegram")  # Telegram alerts lost
+```
+
+## How it works
+
+- **Disk and network are isolated.** Separate queue + worker each, so a slow or down Telegram never delays local logs. The file is the critical path: fast and reliable.
+- **Non-blocking.** `log()` drops and counts when a queue is full instead of freezing your app.
+- **Crash-safe.** Every line is flushed to disk immediately (durability over throughput).
+- **Daily rotation** per named instance, with auto-cleanup after `retention_days`.
+
+```
+logs/
+├── my_app_logs_2025_01_21.log
+├── my_app_errors_2025_01_21.log
+└── worker_1_logs_2025_01_21.log
+```
+
+## Requirements
+
+- Python 3.10+
+- No external dependencies
+
+## License
+
+MIT

easy_tg_logger-0.1.0/README.md

@@ -0,0 +1,99 @@
+# easy_tg_logger
+
+[![PyPI version](https://img.shields.io/pypi/v/easy_tg_logger.svg)](https://pypi.org/project/easy_tg_logger/)
+[![Python](https://img.shields.io/pypi/pyversions/easy_tg_logger.svg)](https://pypi.org/project/easy_tg_logger/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+Fast, minimal async logger for local files with optional Telegram alerts. **Zero dependencies** (stdlib only).
+
+## Install
+
+```bash
+pip install easy_tg_logger
+```
+
+## Usage
+
+```python
+from pytelegram_logger import init_telegram_logger, log, shutdown_logger
+
+init_telegram_logger(name="my_app")
+
+log("App started")
+log("Database error", is_error=True)
+
+shutdown_logger()  # optional, flushes pending logs
+```
+
+### With Telegram alerts
+
+```python
+init_telegram_logger(
+    name="my_app",
+    telegram_token_logs="BOT_TOKEN_1",     # routine logs
+    telegram_token_errors="BOT_TOKEN_2",   # error alerts
+    telegram_chat_ids=["-1001234567890"],
+)
+
+log("Payment received", send_telegram=True)
+log("Critical failure", is_error=True, send_telegram=True)
+```
+
+Two tokens = two channels: routine logs stay separate from high-priority error alerts.
+
+## API
+
+### `init_telegram_logger(name, ...)`
+
+| Argument | Default | Description |
+|---|---|---|
+| `name` | — | **Required.** Unique instance id (e.g. `"api"`, `"worker_1"`). |
+| `log_dir` | `"logs"` | Directory for log files. |
+| `telegram_token_logs` | `None` | Bot token for routine logs. |
+| `telegram_token_errors` | `None` | Bot token for errors. |
+| `telegram_chat_ids` | `[]` | List of chat IDs. |
+| `retention_days` | `30` | Auto-delete files older than N days. |
+| `queue_maxsize` | `10000` | Max pending messages per queue. |
+
+### `log(message, is_error=False, send_telegram=False, save=True)`
+
+- `is_error=True` → error file + error token
+- `send_telegram=True` → also send to Telegram
+- `save=False` → Telegram only, no file
+
+### `shutdown_logger()`
+
+Graceful shutdown: drains queues and closes files. Optional but recommended.
+
+### `get_dropped_count(sink=None)`
+
+Messages dropped because a queue was full (logging never blocks the caller).
+
+```python
+get_dropped_count()            # total (disk + Telegram)
+get_dropped_count("file")      # local logs lost  ← the one that matters
+get_dropped_count("telegram")  # Telegram alerts lost
+```
+
+## How it works
+
+- **Disk and network are isolated.** Separate queue + worker each, so a slow or down Telegram never delays local logs. The file is the critical path: fast and reliable.
+- **Non-blocking.** `log()` drops and counts when a queue is full instead of freezing your app.
+- **Crash-safe.** Every line is flushed to disk immediately (durability over throughput).
+- **Daily rotation** per named instance, with auto-cleanup after `retention_days`.
+
+```
+logs/
+├── my_app_logs_2025_01_21.log
+├── my_app_errors_2025_01_21.log
+└── worker_1_logs_2025_01_21.log
+```
+
+## Requirements
+
+- Python 3.10+
+- No external dependencies
+
+## License
+
+MIT

easy_tg_logger-0.1.0/pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "easy_tg_logger"
+version = "0.1.0"
+authors = [
+    {name = "Beltrán Offerrall"}
+]
+description = "Minimal Python logger with Telegram notifications"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/offerrall/py-telegram-logger"
+Repository = "https://github.com/offerrall/py-telegram-logger"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["pytelegram_logger*"]

easy_tg_logger-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

easy_tg_logger-0.1.0/src/easy_tg_logger.egg-info/PKG-INFO

@@ -0,0 +1,111 @@
+Metadata-Version: 2.4
+Name: easy_tg_logger
+Version: 0.1.0
+Summary: Minimal Python logger with Telegram notifications
+Author: Beltrán Offerrall
+Project-URL: Homepage, https://github.com/offerrall/py-telegram-logger
+Project-URL: Repository, https://github.com/offerrall/py-telegram-logger
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# easy_tg_logger
+
+[![PyPI version](https://img.shields.io/pypi/v/easy_tg_logger.svg)](https://pypi.org/project/easy_tg_logger/)
+[![Python](https://img.shields.io/pypi/pyversions/easy_tg_logger.svg)](https://pypi.org/project/easy_tg_logger/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+Fast, minimal async logger for local files with optional Telegram alerts. **Zero dependencies** (stdlib only).
+
+## Install
+
+```bash
+pip install easy_tg_logger
+```
+
+## Usage
+
+```python
+from pytelegram_logger import init_telegram_logger, log, shutdown_logger
+
+init_telegram_logger(name="my_app")
+
+log("App started")
+log("Database error", is_error=True)
+
+shutdown_logger()  # optional, flushes pending logs
+```
+
+### With Telegram alerts
+
+```python
+init_telegram_logger(
+    name="my_app",
+    telegram_token_logs="BOT_TOKEN_1",     # routine logs
+    telegram_token_errors="BOT_TOKEN_2",   # error alerts
+    telegram_chat_ids=["-1001234567890"],
+)
+
+log("Payment received", send_telegram=True)
+log("Critical failure", is_error=True, send_telegram=True)
+```
+
+Two tokens = two channels: routine logs stay separate from high-priority error alerts.
+
+## API
+
+### `init_telegram_logger(name, ...)`
+
+| Argument | Default | Description |
+|---|---|---|
+| `name` | — | **Required.** Unique instance id (e.g. `"api"`, `"worker_1"`). |
+| `log_dir` | `"logs"` | Directory for log files. |
+| `telegram_token_logs` | `None` | Bot token for routine logs. |
+| `telegram_token_errors` | `None` | Bot token for errors. |
+| `telegram_chat_ids` | `[]` | List of chat IDs. |
+| `retention_days` | `30` | Auto-delete files older than N days. |
+| `queue_maxsize` | `10000` | Max pending messages per queue. |
+
+### `log(message, is_error=False, send_telegram=False, save=True)`
+
+- `is_error=True` → error file + error token
+- `send_telegram=True` → also send to Telegram
+- `save=False` → Telegram only, no file
+
+### `shutdown_logger()`
+
+Graceful shutdown: drains queues and closes files. Optional but recommended.
+
+### `get_dropped_count(sink=None)`
+
+Messages dropped because a queue was full (logging never blocks the caller).
+
+```python
+get_dropped_count()            # total (disk + Telegram)
+get_dropped_count("file")      # local logs lost  ← the one that matters
+get_dropped_count("telegram")  # Telegram alerts lost
+```
+
+## How it works
+
+- **Disk and network are isolated.** Separate queue + worker each, so a slow or down Telegram never delays local logs. The file is the critical path: fast and reliable.
+- **Non-blocking.** `log()` drops and counts when a queue is full instead of freezing your app.
+- **Crash-safe.** Every line is flushed to disk immediately (durability over throughput).
+- **Daily rotation** per named instance, with auto-cleanup after `retention_days`.
+
+```
+logs/
+├── my_app_logs_2025_01_21.log
+├── my_app_errors_2025_01_21.log
+└── worker_1_logs_2025_01_21.log
+```
+
+## Requirements
+
+- Python 3.10+
+- No external dependencies
+
+## License
+
+MIT

easy_tg_logger-0.1.0/src/easy_tg_logger.egg-info/SOURCES.txt

@@ -0,0 +1,8 @@
+LICENSE
+README.md
+pyproject.toml
+src/easy_tg_logger.egg-info/PKG-INFO
+src/easy_tg_logger.egg-info/SOURCES.txt
+src/easy_tg_logger.egg-info/dependency_links.txt
+src/easy_tg_logger.egg-info/top_level.txt
+src/pytelegram_logger/__init__.py

easy_tg_logger-0.1.0/src/easy_tg_logger.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

easy_tg_logger-0.1.0/src/easy_tg_logger.egg-info/top_level.txt

@@ -0,0 +1 @@
+pytelegram_logger

easy_tg_logger-0.1.0/src/pytelegram_logger/__init__.py

@@ -0,0 +1,384 @@
+import threading
+import time
+import html
+import json
+import urllib.request
+import urllib.error
+from datetime import datetime, timedelta
+from pathlib import Path
+from queue import Queue, Empty, Full
+from dataclasses import dataclass, field
+import sys
+
+__all__ = ['init_telegram_logger', 'log', 'shutdown_logger', 'get_dropped_count']
+
+
+@dataclass
+class LoggerState:
+    log_dir: Path | None = None
+    telegram_token_logs: str | None = None
+    telegram_token_errors: str | None = None
+    telegram_chat_ids: list = field(default_factory=list)
+    retention_days: int = 30
+    name: str = ""
+
+    file_queue: Queue | None = None
+    telegram_queue: Queue | None = None
+
+    running: bool = False
+    file_worker_thread: threading.Thread | None = None
+    telegram_worker_thread: threading.Thread | None = None
+    cleanup_thread: threading.Thread | None = None
+
+    log_file: object = None
+    error_file: object = None
+    current_log_path: str = ""
+    current_error_path: str = ""
+
+    cached_date: str = ""
+    cached_log_path: Path | None = None
+    cached_error_path: Path | None = None
+
+    dropped_file: int = 0
+    dropped_telegram: int = 0
+    dropped_lock: threading.Lock = field(default_factory=threading.Lock)
+
+
+state = LoggerState()
+
+
+def init_telegram_logger(
+    log_dir: str = "logs",
+    telegram_token_logs: str | None = None,
+    telegram_token_errors: str | None = None,
+    telegram_chat_ids: list | None = None,
+    retention_days: int = 30,
+    name: str = "",
+    queue_maxsize: int = 10000,
+) -> None:
+    """Initialize the Telegram logger with specified configuration.
+
+    Args:
+        log_dir: Directory where log files will be stored
+        telegram_token_logs: Bot token for general log notifications
+        telegram_token_errors: Bot token for error notifications
+        telegram_chat_ids: List of Telegram chat IDs to send notifications to
+        retention_days: Number of days to keep log files before auto-deletion
+        name: Unique identifier for this logger instance (required)
+        queue_maxsize: Max pending messages per queue (file and Telegram have
+            independent queues). When a queue is full, new messages for that
+            sink are dropped and counted (see get_dropped_count()).
+
+    Raises:
+        RuntimeError: If logger is already initialized
+        ValueError: If name is empty or whitespace
+    """
+    if state.running:
+        raise RuntimeError("Logger already initialized")
+
+    if not name or name.strip() == "":
+        raise ValueError("Logger name must be provided, cannot be empty")
+
+    state.log_dir = Path(log_dir)
+    state.log_dir.mkdir(exist_ok=True)
+
+    state.telegram_token_logs = telegram_token_logs
+    state.telegram_token_errors = telegram_token_errors
+    state.telegram_chat_ids = telegram_chat_ids or []
+    state.retention_days = retention_days
+    state.name = name
+
+    state.file_queue = Queue(maxsize=queue_maxsize)
+    state.telegram_queue = Queue(maxsize=queue_maxsize)
+    state.dropped_file = 0
+    state.dropped_telegram = 0
+    state.running = True
+
+    state.file_worker_thread = threading.Thread(target=file_worker, daemon=True)
+    state.file_worker_thread.start()
+
+    state.telegram_worker_thread = threading.Thread(target=telegram_worker, daemon=True)
+    state.telegram_worker_thread.start()
+
+    state.cleanup_thread = threading.Thread(target=cleanup_worker, daemon=True)
+    state.cleanup_thread.start()
+
+
+def get_daily_file(is_error: bool = False) -> Path:
+    """Get the path for today's log file.
+
+    Args:
+        is_error: If True, return error log path; otherwise return general log path
+
+    Returns:
+        Path object for the appropriate log file
+    """
+    now = datetime.now()
+    date_str = f"{now.year}_{now.month:02d}_{now.day:02d}"
+
+    if state.cached_date != date_str:
+        state.cached_log_path = state.log_dir / f"{state.name}_logs_{date_str}.log"
+        state.cached_error_path = state.log_dir / f"{state.name}_errors_{date_str}.log"
+        state.cached_date = date_str
+
+    return state.cached_error_path if is_error else state.cached_log_path
+
+
+def write_to_file(message: str, is_error: bool = False) -> None:
+    """Write a log message to the appropriate file.
+
+    Args:
+        message: The log message to write
+        is_error: If True, write to error log; otherwise write to general log
+    """
+    filepath = get_daily_file(is_error)
+    filepath_str = str(filepath)
+
+    now = datetime.now()
+    timestamp = '%04d-%02d-%02d %02d:%02d:%02d' % (now.year, now.month, now.day, now.hour, now.minute, now.second)
+
+    if is_error:
+        if state.current_error_path != filepath_str:
+            if state.error_file:
+                state.error_file.close()
+            state.error_file = open(filepath, "a", encoding="utf-8")
+            state.current_error_path = filepath_str
+
+        file_handle = state.error_file
+    else:
+        if state.current_log_path != filepath_str:
+            if state.log_file:
+                state.log_file.close()
+            state.log_file = open(filepath, "a", encoding="utf-8")
+            state.current_log_path = filepath_str
+
+        file_handle = state.log_file
+
+    file_handle.write(f"[{timestamp}] {message}\n")
+    file_handle.flush()
+
+
+def send_telegram(message: str, is_error: bool = False) -> None:
+    """Send a log message to Telegram.
+
+    Args:
+        message: The log message to send
+        is_error: If True, use error token and prefix; otherwise use log token
+    """
+    token = state.telegram_token_errors if is_error else state.telegram_token_logs
+
+    if not token or not state.telegram_chat_ids:
+        return
+
+    log_type = "🔴 ERROR" if is_error else "ℹ️ LOG"
+    full_message = f"{log_type}\n\n{html.escape(message)}"
+
+    url = f"https://api.telegram.org/bot{token}/sendMessage"
+
+    for chat_id in state.telegram_chat_ids:
+        try:
+            data = json.dumps({
+                "chat_id": chat_id,
+                "text": full_message,
+                "parse_mode": "HTML",
+            }).encode("utf-8")
+
+            req = urllib.request.Request(
+                url,
+                data=data,
+                headers={"Content-Type": "application/json"},
+                method="POST",
+            )
+            urllib.request.urlopen(req, timeout=5)
+            time.sleep(0.05)
+        except urllib.error.URLError as e:
+            print(f"[pytelegram_logger] Telegram API error for chat {chat_id}: {e}", file=sys.stderr)
+        except Exception as e:
+            print(f"[pytelegram_logger] Unexpected error sending to Telegram chat {chat_id}: {e}", file=sys.stderr)
+
+
+def file_worker() -> None:
+    """Background worker thread that writes log messages to disk."""
+    while state.running:
+        try:
+            item = state.file_queue.get(timeout=1)
+        except Empty:
+            continue
+
+        if item is None:
+            state.file_queue.task_done()
+            break
+
+        message, is_error = item
+        try:
+            write_to_file(message, is_error)
+        except Exception as e:
+            print(f"[pytelegram_logger] Error writing log to file: {e}", file=sys.stderr)
+        finally:
+            state.file_queue.task_done()
+
+
+def telegram_worker() -> None:
+    """Background worker thread that sends log messages to Telegram."""
+    while state.running:
+        try:
+            item = state.telegram_queue.get(timeout=1)
+        except Empty:
+            continue
+
+        if item is None:
+            state.telegram_queue.task_done()
+            break
+
+        message, is_error = item
+        try:
+            send_telegram(message, is_error)
+        except Exception as e:
+            print(f"[pytelegram_logger] Error sending log to Telegram: {e}", file=sys.stderr)
+        finally:
+            state.telegram_queue.task_done()
+
+
+def cleanup_old_logs() -> None:
+    """Delete log files older than the configured retention period."""
+    if state.log_dir is None:
+        return
+
+    cutoff_date = datetime.now() - timedelta(days=state.retention_days)
+
+    log_pattern = f"{state.name}_logs_*.log"
+    error_pattern = f"{state.name}_errors_*.log"
+
+    for pattern in [log_pattern, error_pattern]:
+        for log_file in state.log_dir.glob(pattern):
+            try:
+                mtime = datetime.fromtimestamp(log_file.stat().st_mtime)
+                if mtime < cutoff_date:
+                    log_file.unlink()
+            except (OSError, ValueError) as e:
+                print(f"[pytelegram_logger] Error deleting old log file {log_file}: {e}", file=sys.stderr)
+            except Exception as e:
+                print(f"[pytelegram_logger] Unexpected error during cleanup of {log_file}: {e}", file=sys.stderr)
+
+
+def cleanup_worker() -> None:
+    """Background worker thread that periodically cleans up old log files."""
+    while state.running:
+        time.sleep(3600)
+        cleanup_old_logs()
+
+
+def shutdown_logger() -> None:
+    """Gracefully shutdown the logger and close all resources.
+
+    Waits for all queued messages (file and Telegram) to be processed before
+    shutting down.
+    """
+    if not state.running:
+        return
+
+    if state.file_queue:
+        state.file_queue.join()
+    if state.telegram_queue:
+        state.telegram_queue.join()
+
+    state.running = False
+
+    if state.file_worker_thread:
+        state.file_worker_thread.join(timeout=5)
+
+    if state.telegram_worker_thread:
+        state.telegram_worker_thread.join(timeout=5)
+
+    if state.cleanup_thread:
+        state.cleanup_thread.join(timeout=1)
+
+    if state.log_file:
+        state.log_file.close()
+        state.log_file = None
+
+    if state.error_file:
+        state.error_file.close()
+        state.error_file = None
+
+
+def _drop_file() -> None:
+    """Increment the dropped-file-message counter (thread-safe)."""
+    with state.dropped_lock:
+        state.dropped_file += 1
+
+
+def _drop_telegram() -> None:
+    """Increment the dropped-Telegram-message counter (thread-safe)."""
+    with state.dropped_lock:
+        state.dropped_telegram += 1
+
+
+def get_dropped_count(sink: str | None = None) -> int:
+    """Return how many messages were dropped because a queue was full.
+
+    Useful to detect a saturated disk sink or a stuck/down Telegram without
+    ever blocking the application. Disk and Telegram are counted separately:
+    losing a local log is worse than losing a Telegram notification.
+
+    Args:
+        sink: "file" for disk-only, "telegram" for Telegram-only, or None
+            (default) for the combined total.
+
+    Returns:
+        Number of dropped messages for the requested sink. Returns 0 cleanly
+        even if called before init_telegram_logger().
+
+    Raises:
+        ValueError: If sink is not None, "file" or "telegram".
+    """
+    if sink not in (None, "file", "telegram"):
+        raise ValueError('sink must be None, "file" or "telegram"')
+
+    with state.dropped_lock:
+        if sink == "file":
+            return state.dropped_file
+        if sink == "telegram":
+            return state.dropped_telegram
+        return state.dropped_file + state.dropped_telegram
+
+
+def log(message: str, is_error: bool = False, send_telegram: bool = False, save: bool = True) -> None:
+    """Log a message to file and/or Telegram.
+
+    Non-blocking: if a queue is full the message is dropped and counted
+    (see get_dropped_count()). Logging must never freeze the caller.
+
+    Args:
+        message: The message to log
+        is_error: If True, treat as error (different file and Telegram token)
+        send_telegram: If True, send notification to Telegram
+        save: If True, save to log file; if False, only send to Telegram
+
+    Raises:
+        RuntimeError: If logger not initialized
+        ValueError: If Telegram is requested but not properly configured
+    """
+    if not state.running or state.file_queue is None or state.telegram_queue is None:
+        raise RuntimeError("Logger not initialized. Call init_telegram_logger() first")
+
+    if send_telegram and not state.telegram_chat_ids:
+        raise ValueError("Telegram chat IDs not configured")
+
+    if send_telegram and is_error and not state.telegram_token_errors:
+        raise ValueError("Telegram token for errors not configured")
+
+    if send_telegram and not is_error and not state.telegram_token_logs:
+        raise ValueError("Telegram token for logs not configured")
+
+    if save:
+        try:
+            state.file_queue.put_nowait((message, is_error))
+        except Full:
+            _drop_file()
+
+    if send_telegram:
+        try:
+            state.telegram_queue.put_nowait((message, is_error))
+        except Full:
+            _drop_telegram()