jaylog 0.1.4__py3-none-any.whl

jaylog/__init__.py

@@ -0,0 +1,5 @@
+from jaylog.logger import get_logger, shutdown
+from jaylog.models import LogEntry
+from jaylog.settings import JaylogSettings
+
+__all__ = ["get_logger", "shutdown", "LogEntry", "JaylogSettings"]

jaylog/filters.py

@@ -0,0 +1,7 @@
+import logging
+
+
+class ExceptionFlagFilter(logging.Filter):
+    def filter(self, record: logging.LogRecord) -> bool:
+        record.is_exception = bool(record.exc_info and record.exc_info[0] is not None)
+        return True

jaylog/formatters.py

@@ -0,0 +1,110 @@
+import getpass
+import io
+import logging
+import socket
+import sys
+import traceback
+from datetime import datetime, timezone
+
+
+def _get_host_info() -> tuple[str, str, str]:
+    hostname = socket.gethostname()
+    try:
+        with socket.socket(socket.AF_INET, socket.SOCK_DGRAM) as s:
+            s.connect(("8.8.8.8", 80))
+            host_ip = s.getsockname()[0]
+    except OSError:
+        host_ip = "unknown"
+    try:
+        username = getpass.getuser()
+    except Exception:
+        username = "unknown"
+    return username, hostname, host_ip
+
+
+_HOST_USERNAME, _HOSTNAME, _HOST_IP = _get_host_info()
+
+_screenshot_enabled: bool = True
+
+_MAX_BYTES = 1 * 1024 * 1024  # 1 MB
+
+
+def configure_screenshot(enabled: bool) -> None:
+    global _screenshot_enabled
+    _screenshot_enabled = enabled
+
+
+def _capture_screenshot() -> bytes | None:
+    if not _screenshot_enabled:
+        return None
+    try:
+        from PIL import ImageGrab
+
+        img = ImageGrab.grab()
+
+        quality = 85
+        scale = 1.0
+        buf = io.BytesIO()
+
+        while True:
+            buf.seek(0)
+            buf.truncate()
+
+            current = img
+            if scale < 1.0:
+                w = int(img.width * scale)
+                h = int(img.height * scale)
+                current = img.resize((w, h))
+
+            current.save(buf, format="JPEG", quality=quality, optimize=True)
+
+            if buf.tell() <= _MAX_BYTES:
+                break
+
+            if quality > 30:
+                quality -= 10
+            elif scale > 0.5:
+                scale -= 0.1
+            else:
+                break
+
+        buf.seek(0)
+        return buf.read()
+    except Exception as exc:
+        print(f"[jaylog] screenshot: {exc}", file=sys.stderr)
+        return None
+
+
+def build_log_entry_dict(record: logging.LogRecord) -> dict:
+    is_exception = getattr(record, "is_exception", False)
+
+    log_message = record.getMessage()
+    if is_exception and record.exc_info:
+        tb = "".join(traceback.format_exception(*record.exc_info)).strip()
+        log_message = f"{log_message}\n{tb}"
+
+    return {
+        "log_timestamp": datetime.fromtimestamp(record.created, tz=timezone.utc).isoformat(),
+        "log_level": "EXCEPTION" if is_exception else record.levelname,
+        "is_exception": is_exception,
+        "log_message": log_message,
+        "service": record.name,
+        "username": _HOST_USERNAME,
+        "hostname": _HOSTNAME,
+        "ipv4": _HOST_IP,
+        "service_path": record.pathname,
+        "log_img": _capture_screenshot() if (record.levelno >= logging.ERROR or is_exception) else None,
+    }
+
+
+class PlainTextFormatter(logging.Formatter):
+    """Human-readable single-line formatter for .log files."""
+
+    def format(self, record: logging.LogRecord) -> str:
+        entry = build_log_entry_dict(record)
+        line = (
+            f"{entry['log_timestamp']} [{entry['log_level']}]"
+            f" {entry['service']} {entry['hostname']}({entry['ipv4']}) {entry['username']}"
+            f" | {entry['log_message']}"
+        )
+        return line

jaylog/handlers/__init__.py

@@ -0,0 +1,4 @@
+from .file_handler import JaylogFileHandler
+from .http_handler import JaylogHttpHandler
+
+__all__ = ["JaylogFileHandler", "JaylogHttpHandler"]

jaylog/handlers/file_handler.py

@@ -0,0 +1,51 @@
+import time
+from logging.handlers import RotatingFileHandler
+from pathlib import Path
+
+from jaylog.formatters import PlainTextFormatter
+
+
+class JaylogFileHandler(RotatingFileHandler):
+    """
+    Rotating file handler that:
+    - rotates when the file reaches `maxBytes` (default 5 MB)
+    - deletes backup files older than `retention_days` (default 7) after each rollover
+    """
+
+    def __init__(
+        self,
+        filename: Path,
+        max_bytes: int = 5 * 1024 * 1024,
+        backup_count: int = 20,
+        retention_days: int = 7,
+        encoding: str = "utf-8",
+    ) -> None:
+        filename.parent.mkdir(parents=True, exist_ok=True)
+        super().__init__(
+            filename,
+            maxBytes=max_bytes,
+            backupCount=backup_count,
+            encoding=encoding,
+        )
+        self.retention_days = retention_days
+        self.setFormatter(PlainTextFormatter())
+
+    def doRollover(self) -> None:
+        super().doRollover()
+        self._purge_old_logs()
+
+    def _purge_old_logs(self) -> None:
+        base = Path(self.baseFilename)
+        cutoff = time.time() - self.retention_days * 86400
+
+        for entry in base.parent.iterdir():
+            if not entry.is_file():
+                continue
+            # Match rotated backups: app.log.1, app.log.2, ...
+            if entry.name == base.name or not entry.name.startswith(base.name):
+                continue
+            try:
+                if entry.stat().st_mtime < cutoff:
+                    entry.unlink()
+            except OSError:
+                pass

jaylog/handlers/http_handler.py

@@ -0,0 +1,79 @@
+import json
+import logging
+import warnings
+from importlib.metadata import PackageNotFoundError, version
+
+import requests
+import urllib3
+
+from jaylog.formatters import build_log_entry_dict
+from jaylog.settings import JaylogSettings
+
+settings = JaylogSettings()
+
+try:
+    _JAYLOG_VERSION = version("jaylog")
+except PackageNotFoundError:
+    _JAYLOG_VERSION = "unknown"
+
+proxies = {
+    'http': settings.log_http_proxy,
+    'https': settings.log_http_proxy  
+}
+
+session = requests.Session()
+if settings.log_http_proxy:
+    session.proxies.update(proxies)
+
+def _to_multipart(fields: dict) -> dict:
+    result = {}
+    for key, value in fields.items():
+        if value is None:
+            continue
+        if isinstance(value, bytes):
+            result[key] = ("screenshot.jpg", value, "image/jpeg")
+        elif isinstance(value, bool):
+            result[key] = (None, "true" if value else "false")
+        elif not isinstance(value, str):
+            result[key] = (None, json.dumps(value))
+        else:
+            result[key] = (None, value)
+    return result
+
+
+class JaylogHttpHandler(logging.Handler):
+    """
+    HTTP handler that POSTs log records as multipart/form-data to a remote endpoint.
+
+    Non-blocking behaviour is guaranteed by the QueueListener that drives this
+    handler — emit() runs in the listener's background thread.
+    """
+
+    def __init__(
+        self,
+        endpoint: str,
+        api_key: str,
+        timeout: float = 5.0,
+    ) -> None:
+        super().__init__()
+        self.endpoint = endpoint
+        self.timeout = timeout
+        self._session = session
+        self._session.headers["x-api-key"] = api_key
+        self._session.headers["x-jaylog-version"] = _JAYLOG_VERSION
+
+    def mapLogRecord(self, record: logging.LogRecord) -> dict:
+        return build_log_entry_dict(record)
+
+    def emit(self, record: logging.LogRecord) -> None:
+        try:
+            with warnings.catch_warnings():
+                warnings.simplefilter("ignore", urllib3.exceptions.InsecureRequestWarning)
+                self._session.post(
+                    self.endpoint,
+                    files=_to_multipart(self.mapLogRecord(record)),
+                    timeout=self.timeout,
+                    verify=False,
+                )
+        except Exception:
+            pass

jaylog/logger.py

@@ -0,0 +1,116 @@
+import atexit
+import logging
+import os
+import signal
+from logging.handlers import QueueHandler, QueueListener
+from queue import Queue
+
+from jaylog.filters import ExceptionFlagFilter
+from jaylog.formatters import configure_screenshot
+from jaylog.handlers.file_handler import JaylogFileHandler
+from jaylog.handlers.http_handler import JaylogHttpHandler
+from jaylog.settings import JaylogSettings
+
+# Registry: name -> (logger, listener) so callers can shut down cleanly
+_registry: dict[str, tuple[logging.Logger, QueueListener]] = {}
+_shutdown_registered = False
+
+
+def _register_shutdown_hooks() -> None:
+    global _shutdown_registered
+    if _shutdown_registered:
+        return
+    _shutdown_registered = True
+
+    atexit.register(shutdown)
+
+    def _sigterm_handler(signum, frame):  # noqa: ANN001
+        shutdown()
+        signal.signal(signal.SIGTERM, signal.SIG_DFL)
+        signal.raise_signal(signal.SIGTERM)
+
+    signal.signal(signal.SIGTERM, _sigterm_handler)
+
+
+def get_logger(settings: JaylogSettings | None = None) -> logging.Logger:
+    """
+    Return a configured logger.
+
+    The logger name is read from JAYLOG_LOGGER_NAME (default: "jaylog").
+    Calling this multiple times with the same logger name returns the **same**
+    logger without re-attaching handlers.
+
+    Architecture:
+        logger  →  QueueHandler  →  Queue  →  QueueListener  →  [FileHandler, HttpHandler?]
+
+    The QueueListener runs in a background thread so `emit()` never blocks the
+    calling thread.
+    """
+    if settings is None:
+        settings = JaylogSettings()
+
+    name = settings.app_name
+
+    configure_screenshot(settings.log_screenshot_enabled)
+
+    if name in _registry:
+        return _registry[name][0]
+
+    # ------------------------------------------------------------------
+    # Build the actual (downstream) handlers
+    # ------------------------------------------------------------------
+    downstream: list[logging.Handler] = []
+
+    log_path = settings.log_dir / settings.log_filename
+    file_handler = JaylogFileHandler(
+        filename=log_path,
+        max_bytes=settings.log_max_bytes,
+        backup_count=settings.log_backup_count,
+        retention_days=settings.log_retention_days,
+    )
+    file_handler.setLevel(settings.log_level)
+    downstream.append(file_handler)
+
+    if settings.log_http_endpoint and settings.log_http_api_key:
+        http_handler = JaylogHttpHandler(
+            endpoint=settings.log_http_endpoint,
+            api_key=settings.log_http_api_key,
+            timeout=settings.log_http_timeout,
+        )
+        http_handler.setLevel(settings.log_level)
+        downstream.append(http_handler)
+
+    # ------------------------------------------------------------------
+    # Wire up the Queue + QueueListener
+    # ------------------------------------------------------------------
+    queue: Queue = Queue(maxsize=-1)  # unbounded
+    queue_handler = QueueHandler(queue)
+    queue_handler.addFilter(ExceptionFlagFilter())
+
+    listener = QueueListener(queue, *downstream, respect_handler_level=True)
+    listener.start()
+
+    # ------------------------------------------------------------------
+    # Configure the logger
+    # ------------------------------------------------------------------
+    logger = logging.getLogger(name)
+    logger.setLevel(settings.log_level)
+    logger.addHandler(queue_handler)
+    logger.propagate = False
+
+    _registry[name] = (logger, listener)
+    _register_shutdown_hooks()
+    return logger
+
+
+def shutdown(name: str | None = None) -> None:
+    """
+    Stop the QueueListener(s) gracefully, flushing any remaining records.
+
+    Pass a logger `name` to stop a single logger, or omit to stop all.
+    """
+    targets = [name] if name else list(_registry.keys())
+    for n in targets:
+        if n in _registry:
+            _, listener = _registry.pop(n)
+            listener.stop()

jaylog/models.py

@@ -0,0 +1,16 @@
+from datetime import datetime
+from typing import Optional
+from pydantic import BaseModel
+
+
+class LogEntry(BaseModel):
+    log_timestamp: datetime
+    log_level: str
+    is_exception: bool
+    log_message: str
+    service: str
+    username: str
+    hostname: str
+    ipv4: str
+    service_path: str
+    log_img: Optional[str] = None

jaylog/settings.py

@@ -0,0 +1,57 @@
+from pathlib import Path
+from typing import Optional
+
+from pydantic import computed_field, field_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+from jaylog.formatters import _HOSTNAME, _HOST_USERNAME
+
+
+class JaylogSettings(BaseSettings):
+    model_config = SettingsConfigDict(
+        env_prefix="JAYLOG_",
+        env_file=('.env.logging', '.env'),
+        env_file_encoding='utf-8',
+        secrets_dir='secrets',
+        extra="ignore"
+    )
+
+    # App identity
+    app_name: str
+    log_dir: Path
+
+    secrets_dir: Path | None = None
+
+    # File handler
+    log_level: str = "INFO"
+    log_max_bytes: int = 5 * 1024 * 1024  # 5 MB
+    log_backup_count: int = 5
+    log_retention_days: int = 7
+
+    # HTTP handler
+    log_http_endpoint: Optional[str] = None
+    log_http_api_key: Optional[str] = None
+    log_http_timeout: float = 5.0
+    log_http_proxy: Optional[str] = None
+
+    # Screenshot (log_img field) — desativar com JAYLOG_LOG_SCREENSHOT_ENABLED=false
+    log_screenshot_enabled: bool = False
+
+    @field_validator("log_dir", mode="after")
+    @classmethod
+    def validate_log_dir(cls, v: Path) -> Path:
+        if v.exists() and not v.is_dir():
+            raise ValueError(f"JAYLOG_LOG_DIR '{v}' exists but is not a directory")
+        return v
+
+    @computed_field
+    @property
+    def log_filename(self) -> Path:
+        return Path(f"{self.app_name}_{_HOSTNAME}_{_HOST_USERNAME}.log")
+
+    def reload_secrets(self):
+        if self.secrets_dir:
+            if not self.secrets_dir.exists() or not self.secrets_dir.is_dir:
+                raise ValueError('SECRETS_DIR is not valid directory')
+                
+        return JaylogSettings(_secrets_dir=self.secrets_dir)  # ty:ignore[missing-argument, unknown-argument]

jaylog-0.1.4.dist-info/METADATA

@@ -0,0 +1,120 @@
+Metadata-Version: 2.3
+Name: jaylog
+Version: 0.1.4
+Summary: Customized Python logging library with file rotation and HTTP forwarding
+Author: Gpocas
+Author-email: Gpocas <gpocas01@gmail.com>
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Natural Language :: Portuguese (Brazilian)
+Classifier: Development Status :: 5 - Production/Stable
+Requires-Dist: pydantic>=2.0,<3.0
+Requires-Dist: pydantic-settings>=2.0,<3.0
+Requires-Dist: requests>=2.32,<3.0
+Requires-Dist: pillow>=11.0,<13.0
+Requires-Python: >=3.10, <3.14
+Project-URL: repository, https://github.com/Gpocas/jaylog
+Project-URL: Bug Tracker, https://github.com/Gpocas/jaylog/issues
+Description-Content-Type: text/markdown
+
+# jaylog
+
+Biblioteca de logging para Python com rotação de arquivos e envio HTTP para um endpoint remoto.
+
+## Instalação
+
+```bash
+pip install -U --no-cache-dir git+https://github.com/Gpocas/jaylog.git
+```
+
+## Variáveis de ambiente
+
+As variáveis usam o prefixo `JAYLOG_`. Podem ser definidas no ambiente do sistema ou em um arquivo `.env` / `.env.logging` na raiz do projeto.
+
+| Variável                        | obrigatorio? | Padrão    | Descrição                                                               |
+| ------------------------------- | ------------ | --------- | ----------------------------------------------------------------------- |
+| `JAYLOG_APP_NAME`               | SIM          | `null`    | Nome do serviço/bot (usado no nome do arquivo de log)                   |
+| `JAYLOG_LOG_DIR`                | SIM          | `null`    | Caminho do diretório onde os arquivos de log serão salvos               |
+| `JAYLOG_LOG_LEVEL`              | NÃO          | `INFO`    | Nível mínimo de log (`DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`)   |
+| `JAYLOG_LOG_MAX_BYTES`          | NÃO          | `5242880` | Tamanho máximo do arquivo de log antes de rotacionar (bytes)            |
+| `JAYLOG_LOG_BACKUP_COUNT`       | NÃO          | `5`       | Quantidade de arquivos de backup mantidos após rotação                  |
+| `JAYLOG_LOG_RETENTION_DAYS`     | NÃO          | `7`       | Dias para manter arquivos de log antigos                                |
+| `JAYLOG_LOG_HTTP_TIMEOUT`       | NÃO          | `5.0`     | Timeout em segundos para o envio HTTP                                   |
+| `JAYLOG_LOG_HTTP_ENDPOINT`      | NÃO          | `null`    | URL do endpoint que receberá os logs                                    |
+| `JAYLOG_LOG_HTTP_API_KEY`       | NÃO          | `null`    | Chave de autenticação enviada no header `x-api-key`                     |
+| `JAYLOG_LOG_HTTP_PROXY`         | NÃO          | `null`    | URL do proxy para o envio HTTP (ex: `http:\\user:password@server:port`) |
+| `JAYLOG_LOG_SCREENSHOT_ENABLED` | NÃO          | `false`   | Captura screenshot no momento do log (`true`/`false`, apenas Windows)   |
+
+
+## Uso Simples
+
+__*.env.logging*__
+```env
+JAYLOG_APP_NAME=meu-bot
+JAYLOG_LOG_DIR=C:\logs
+```
+__*main.py*__
+```python
+from jaylog import JaylogSettings, get_logger
+
+logger = get_logger(JaylogSettings())
+
+logger.info("Mensagem de log")
+logger.error("Erro ao processar")
+```
+
+
+## Alterando Caminho padrão do .env
+
+__*development.env*__
+```env
+JAYLOG_APP_NAME=meu-bot
+JAYLOG_LOG_DIR=C:\logs
+```
+
+__*main.py*__
+```python
+from jaylog import JaylogSettings, get_logger
+
+
+settings = JaylogSettings(_env_file='development.env')
+logger = get_logger(settings)
+
+logger.info("Mensagem de log")
+logger.error("Erro ao processar")
+```
+
+
+## Preparando para produção
+
+
+> [!IMPORTANT]
+> **HTTP_ENDPOINT** e **HTTP_API_KEY** (opcionais) 📢
+>
+> - A configuração **HTTP_ENDPOINT** e **HTTP_API_KEY** não precisa ser feita em ambiente local ou de desenvolvimento
+> - Se apenas uma das duas variaveis **HTTP_ENDPOINT** ou **HTTP_API_KEYS** for definida, o envio HTTP é ignorado.
+> - Caso a aplicação execute em um ambiente que usa um proxy ntlm, defina `JAYLOG_LOG_HTTP_PROXY`
+
+
+__*prodution.env*__
+```env
+JAYLOG_APP_NAME=mlleu-bot
+JAYLOG_LOG_DIR=C:\logs
+JAYLOG_LOG_HTTP_ENDPOINT=https://meu-backend.com/logs/add
+JAYLOG_LOG_HTTP_API_KEY=minha-chave
+JAYLOG_LOG_HTTP_PROXY=http://username:password@proxy.com:8080
+```
+
+__*main.py*__
+```python
+from jaylog import JaylogSettings, get_logger
+
+
+settings = JaylogSettings(_env_file='prodution.env', _secrets_dir='/caminho/secrets/')
+logger = get_logger(settings)
+
+logger.info("Mensagem de log")
+logger.error("Erro ao processar")
+```
+
+

jaylog-0.1.4.dist-info/RECORD

@@ -0,0 +1,12 @@
+jaylog/__init__.py,sha256=g4E1iDrLr37thM7SJ01yvw3gcXwnsAGOG-3sa1oi4vA,193
+jaylog/filters.py,sha256=Eky1NvcSTyCgtr6R8BnyyKv6r1u-u2RvY4iZ4whBbtE,224
+jaylog/formatters.py,sha256=s6IBkb7QRiH0gJlCgE7r7k9pCjX7EC0hmcwq-davD68,3058
+jaylog/handlers/__init__.py,sha256=JxJ8Dy-ttJAZGC91gv73DAdithc8qYtIvwdzLMKT05E,142
+jaylog/handlers/file_handler.py,sha256=p-kZRb4CN27z94w_MYTYULy8uE27t6_Wqo1Sp7jJwpc,1563
+jaylog/handlers/http_handler.py,sha256=Sn3zCmgTOBwiivz8aq5VEXo0cDwhqOUPAWE6JFViUMc,2309
+jaylog/logger.py,sha256=MGP33JiPZMlHsewDUYdAcDpzmXTjs8joUP7AnCY3oao,3879
+jaylog/models.py,sha256=3B7tnFuLMfgmRuJbbqguyVvnpdGS7qLyY6E6_1C-m1w,332
+jaylog/settings.py,sha256=YcUBCsW4YuHf1EwwHgTwDw6UwmC-u6sn-viZZhndlZo,1768
+jaylog-0.1.4.dist-info/WHEEL,sha256=GuAqCqoyQuys5_R4zkHUJFlKXw4RpRLNzo31-ui90WQ,81
+jaylog-0.1.4.dist-info/METADATA,sha256=iqI4pyMUttuCz1IlBUzkh-thpYMXhk6uOnOG9RnAR08,4526
+jaylog-0.1.4.dist-info/RECORD,,

jaylog-0.1.4.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.10.12
+Root-Is-Purelib: true
+Tag: py3-none-any