pepe-logger 0.0.3__tar.gz

pepe_logger-0.0.3/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Jose Luis Alonzo Velazquez
+
+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.

pepe_logger-0.0.3/PKG-INFO

@@ -0,0 +1,61 @@
+Metadata-Version: 2.4
+Name: pepe-logger
+Version: 0.0.3
+Summary: Structured JSON logging for distributed systems, with a Go log shipper.
+License: MIT
+License-File: LICENSE
+Keywords: logging,json,observability,distributed-systems,structured-logging
+Author: Jose Luis Alonzo Velazquez
+Author-email: pepemxl@gmail.com
+Requires-Python: >=3.10,<4.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: System :: Logging
+Classifier: Typing :: Typed
+Project-URL: Documentation, https://github.com/pepemxl/pplogger
+Project-URL: Homepage, https://github.com/pepemxl/pplogger
+Project-URL: Repository, https://github.com/pepemxl/pplogger.git
+Description-Content-Type: text/markdown
+
+# PPLogger
+
+A logger package for scaled distributed systems.
+
+The goal is to standarize logs in distribuited systems and permit scale logging process.
+
+This package converts log records into JSON messages.
+
+## Install
+
+```bash
+pip install pepe-logger
+```
+
+The PyPI distribution is named **`pepe-logger`**; the importable package is
+**`pplogger`** (`from pplogger import initializer_logger`).
+
+An example of a log file:
+- `/tmp/service_api.module_pepe_logs.2024_07_13.log`
+
+Example of usage:
+
+```python
+    import logging
+    from pplogger import initializer_logger
+
+    initializer_logger()
+    log = logging.getLogger(__name__)
+
+    log.info("This log info message")
+    log.debug("This log info message")
+    log.error("This log error message")
+    log.exception("This log exception message")
+```

pepe_logger-0.0.3/README.md

@@ -0,0 +1,34 @@
+# PPLogger
+
+A logger package for scaled distributed systems.
+
+The goal is to standarize logs in distribuited systems and permit scale logging process.
+
+This package converts log records into JSON messages.
+
+## Install
+
+```bash
+pip install pepe-logger
+```
+
+The PyPI distribution is named **`pepe-logger`**; the importable package is
+**`pplogger`** (`from pplogger import initializer_logger`).
+
+An example of a log file:
+- `/tmp/service_api.module_pepe_logs.2024_07_13.log`
+
+Example of usage:
+
+```python
+    import logging
+    from pplogger import initializer_logger
+
+    initializer_logger()
+    log = logging.getLogger(__name__)
+
+    log.info("This log info message")
+    log.debug("This log info message")
+    log.error("This log error message")
+    log.exception("This log exception message")
+```

pepe_logger-0.0.3/pplogger/__init__.py

@@ -0,0 +1,24 @@
+"""pplogger - common logger for observability of distributed systems."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from pplogger.context import bind_context, clear_context, context, get_context
+from pplogger.logger import build_log_path, initializer_logger
+
+try:
+    # Single source of truth: the version declared in pyproject.toml, read from
+    # the installed distribution metadata. The distribution is named
+    # "pepe-logger" on PyPI even though the import package is "pplogger".
+    __version__ = version("pepe-logger")
+except PackageNotFoundError:  # running from a source tree that isn't installed
+    __version__ = "0.0.0+unknown"
+
+__all__ = [
+    "build_log_path",
+    "initializer_logger",
+    "bind_context",
+    "clear_context",
+    "context",
+    "get_context",
+    "__version__",
+]

pepe_logger-0.0.3/pplogger/context.py

@@ -0,0 +1,41 @@
+"""Per-context structured fields for log correlation.
+
+Fields bound here (e.g. ``request_id``, ``trace_id``) are merged into every log
+record emitted from the same thread / asyncio task, so callers don't have to
+thread them through ``extra={...}`` on every log call. Explicit ``extra`` fields
+take precedence over bound context fields.
+"""
+
+from __future__ import annotations
+
+import contextlib
+from collections.abc import Iterator
+from contextvars import ContextVar
+from typing import Any
+
+_context: ContextVar[dict[str, Any] | None] = ContextVar("pplogger_context", default=None)
+
+
+def get_context() -> dict[str, Any]:
+    """Return a copy of the fields currently bound to this context."""
+    return dict(_context.get() or {})
+
+
+def bind_context(**fields: Any) -> None:
+    """Merge ``fields`` into the current context (until overwritten/cleared)."""
+    _context.set({**get_context(), **fields})
+
+
+def clear_context() -> None:
+    """Remove all bound context fields."""
+    _context.set(None)
+
+
+@contextlib.contextmanager
+def context(**fields: Any) -> Iterator[None]:
+    """Bind ``fields`` for the duration of the ``with`` block, then restore."""
+    token = _context.set({**get_context(), **fields})
+    try:
+        yield
+    finally:
+        _context.reset(token)

pepe_logger-0.0.3/pplogger/formatters.py

@@ -0,0 +1,118 @@
+"""JSON formatter for pplogger.
+
+Each log record is serialized to a single-line JSON document so downstream
+processors (e.g. the Go shipper in ./processor) can consume it line by line.
+"""
+
+from __future__ import annotations
+
+import datetime as dt
+import json
+import logging
+import os
+import socket
+import traceback
+from typing import Any
+
+from pplogger.context import get_context
+
+# Process id is cached to avoid a syscall per record, but refreshed after fork()
+# so child processes report their own pid instead of inheriting the parent's.
+_PID = os.getpid()
+
+
+def _refresh_pid() -> None:
+    global _PID
+    _PID = os.getpid()
+
+
+if hasattr(os, "register_at_fork"):
+    os.register_at_fork(after_in_child=_refresh_pid)
+
+# logging.LogRecord built-in attributes — anything not in this set is treated
+# as user-supplied `extra={...}` and copied into the JSON payload.
+_RESERVED_RECORD_ATTRS = frozenset(
+    {
+        "name",
+        "msg",
+        "args",
+        "levelname",
+        "levelno",
+        "pathname",
+        "filename",
+        "module",
+        "exc_info",
+        "exc_text",
+        "stack_info",
+        "lineno",
+        "funcName",
+        "created",
+        "msecs",
+        "relativeCreated",
+        "thread",
+        "threadName",
+        "processName",
+        "process",
+        "message",
+        "asctime",
+        "taskName",
+    }
+)
+
+
+class JSONFormatter(logging.Formatter):
+    """Serialize log records as JSON documents."""
+
+    def __init__(self, service: str, module: str, hostname: str | None = None) -> None:
+        super().__init__()
+        self.service = service
+        self.module = module
+        self.hostname = hostname or socket.gethostname()
+
+    def format(self, record: logging.LogRecord) -> str:
+        timestamp = dt.datetime.fromtimestamp(record.created, tz=dt.timezone.utc)
+        payload: dict[str, Any] = {
+            "timestamp": timestamp.isoformat(timespec="milliseconds").replace("+00:00", "Z"),
+            "level": record.levelname,
+            "logger": record.name,
+            "message": record.getMessage(),
+            "service": self.service,
+            "module": self.module,
+            "hostname": self.hostname,
+            "pid": _PID,
+            "source_module": record.module,
+            "function": record.funcName,
+            "line": record.lineno,
+            "thread": record.threadName,
+        }
+
+        if record.exc_info:
+            exc_type, exc_value, exc_tb = record.exc_info
+            payload["exception"] = {
+                "type": exc_type.__name__ if exc_type else None,
+                "message": str(exc_value) if exc_value else None,
+                "traceback": "".join(traceback.format_exception(exc_type, exc_value, exc_tb)),
+            }
+
+        # Collect user `extra={...}` fields, then merge them over the bound
+        # context so explicit per-call fields win on key collisions.
+        extras = {
+            key: _safe(value)
+            for key, value in record.__dict__.items()
+            if key not in _RESERVED_RECORD_ATTRS and not key.startswith("_") and key not in payload
+        }
+        for key, value in {**get_context(), **extras}.items():
+            if key in payload:
+                continue
+            payload[key] = _safe(value)
+
+        return json.dumps(payload, ensure_ascii=False, default=str)
+
+
+def _safe(value: Any) -> Any:
+    """Best-effort conversion of `extra` values to JSON-friendly types."""
+    try:
+        json.dumps(value)
+        return value
+    except (TypeError, ValueError):
+        return repr(value)

pepe_logger-0.0.3/pplogger/logger.py

@@ -0,0 +1,165 @@
+"""Logger initialization for pplogger."""
+
+from __future__ import annotations
+
+import datetime as dt
+import logging
+import os
+import sys
+from collections.abc import Callable
+from logging.handlers import RotatingFileHandler
+from pathlib import Path
+
+from pplogger.formatters import JSONFormatter
+
+DEFAULT_LOG_DIR = Path(os.environ.get("PPLOGGER_DIR", "/tmp"))
+DEFAULT_SERVICE = os.environ.get("PPLOGGER_SERVICE", "service_api")
+DEFAULT_MODULE = os.environ.get("PPLOGGER_MODULE", "module_pepe")
+
+
+def build_log_path(
+    service: str = DEFAULT_SERVICE,
+    module: str = DEFAULT_MODULE,
+    log_dir: str | os.PathLike[str] = DEFAULT_LOG_DIR,
+    when: dt.date | None = None,
+) -> Path:
+    """Return the daily log file path, e.g. /tmp/service_api.module_pepe_logs.2024_07_13.log"""
+    day = (when or dt.date.today()).strftime("%Y_%m_%d")
+    return Path(log_dir) / f"{service}.{module}_logs.{day}.log"
+
+
+class DailyDatedFileHandler(logging.FileHandler):
+    """A ``FileHandler`` that rolls over to a new date-stamped file at midnight.
+
+    Unlike ``TimedRotatingFileHandler`` (which renames the active file and keeps
+    a fixed base name), this preserves pplogger's convention of putting the day
+    in the filename: each calendar day gets its own
+    ``<service>.<module>_logs.<YYYY_MM_DD>.log``. When the local date changes,
+    the current stream is closed and a new dated file is opened.
+
+    ``clock`` is injectable for testing; it defaults to ``datetime.date.today``.
+    """
+
+    def __init__(
+        self,
+        service: str,
+        module: str,
+        log_dir: str | os.PathLike[str],
+        encoding: str | None = None,
+        clock: Callable[[], dt.date] | None = None,
+    ) -> None:
+        self._service = service
+        self._module = module
+        self._log_dir = log_dir
+        self._clock = clock or dt.date.today
+        self._current_day = self._clock()
+        path = build_log_path(service, module, log_dir, self._current_day)
+        super().__init__(path, encoding=encoding)
+
+    def emit(self, record: logging.LogRecord) -> None:
+        today = self._clock()
+        if today != self._current_day:
+            self._roll_to(today)
+        super().emit(record)
+
+    def _roll_to(self, day: dt.date) -> None:
+        self.acquire()
+        try:
+            if self.stream:
+                self.stream.close()
+                self.stream = None
+            self._current_day = day
+            new_path = build_log_path(self._service, self._module, self._log_dir, day)
+            self.baseFilename = os.path.abspath(str(new_path))
+            self.stream = self._open()
+        finally:
+            self.release()
+
+
+def initializer_logger(
+    service: str = DEFAULT_SERVICE,
+    module: str = DEFAULT_MODULE,
+    log_dir: str | os.PathLike[str] = DEFAULT_LOG_DIR,
+    debug: bool = False,
+    console: bool = True,
+    level: int | str | None = None,
+    max_bytes: int = 0,
+    backup_count: int = 0,
+    hostname: str | None = None,
+    rotate_daily: bool = False,
+) -> Path:
+    """Configure the root logger to emit JSON records to a daily file.
+
+    Returns the path of the active log file so callers can hand it to the
+    Go shipper or to tests.
+
+    :param level: explicit level (e.g. ``logging.WARNING`` or ``"WARNING"``).
+        Takes precedence over ``debug`` when given.
+    :param max_bytes: when > 0, rotate the file once it reaches this size using
+        ``RotatingFileHandler`` instead of a plain ``FileHandler``.
+    :param backup_count: number of rotated backups to keep (only with
+        ``max_bytes``).
+    :param hostname: override the ``hostname`` field (defaults to
+        ``socket.gethostname()``); useful in containers where the host id is
+        injected via the environment.
+    :param rotate_daily: when True (and ``max_bytes`` is 0), roll over to a new
+        date-stamped file at midnight via :class:`DailyDatedFileHandler`.
+        Ignored when ``max_bytes`` > 0 (size-based rotation takes precedence).
+    """
+    log_path = build_log_path(service=service, module=module, log_dir=log_dir)
+    log_path.parent.mkdir(parents=True, exist_ok=True)
+
+    resolved_level = _resolve_level(level, debug)
+    formatter = JSONFormatter(
+        service=service,
+        module=module,
+        hostname=hostname or os.environ.get("PPLOGGER_HOSTNAME"),
+    )
+
+    root = logging.getLogger()
+    root.setLevel(resolved_level)
+
+    # Replace any handlers we previously installed so repeat calls are idempotent.
+    for handler in list(root.handlers):
+        if getattr(handler, "_pplogger", False):
+            root.removeHandler(handler)
+            handler.close()
+
+    file_handler: logging.FileHandler
+    if max_bytes > 0:
+        file_handler = RotatingFileHandler(
+            log_path, maxBytes=max_bytes, backupCount=backup_count, encoding="utf-8"
+        )
+    elif rotate_daily:
+        file_handler = DailyDatedFileHandler(service, module, log_dir, encoding="utf-8")
+    else:
+        file_handler = logging.FileHandler(log_path, encoding="utf-8")
+    file_handler.setLevel(resolved_level)
+    file_handler.setFormatter(formatter)
+    file_handler._pplogger = True  # type: ignore[attr-defined]
+    root.addHandler(file_handler)
+
+    if console:
+        stream_handler = logging.StreamHandler(stream=sys.stdout)
+        stream_handler.setLevel(resolved_level)
+        stream_handler.setFormatter(formatter)
+        stream_handler._pplogger = True  # type: ignore[attr-defined]
+        root.addHandler(stream_handler)
+
+    return log_path
+
+
+def _resolve_level(level: int | str | None, debug: bool) -> int:
+    """Resolve the effective numeric level from explicit/debug/env inputs."""
+    if level is not None:
+        if isinstance(level, str):
+            num = logging.getLevelName(level.upper())
+            if not isinstance(num, int):
+                raise ValueError(f"unknown log level: {level!r}")
+            return num
+        return int(level)
+    return logging.DEBUG if debug or _env_truthy("PPLOGGER_DEBUG") else logging.INFO
+
+
+def _env_truthy(name: str) -> bool:
+    return os.environ.get(name, "").strip().lower() in {"1", "true", "yes", "on"}

pepe_logger-0.0.3/pyproject.toml

@@ -0,0 +1,68 @@
+[tool.poetry]
+# Distribution name on PyPI (the importable package is still `pplogger`).
+name = "pepe-logger"
+description = "Structured JSON logging for distributed systems, with a Go log shipper."
+authors = ["Jose Luis Alonzo Velazquez <pepemxl@gmail.com>"]
+readme = "README.md"
+license = "MIT"
+homepage = "https://github.com/pepemxl/pplogger"
+repository = "https://github.com/pepemxl/pplogger.git"
+documentation = "https://github.com/pepemxl/pplogger"
+keywords = ["logging", "json", "observability", "distributed-systems", "structured-logging"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Topic :: System :: Logging",
+    "Typing :: Typed",
+]
+version = "0.0.3"
+packages = [ {include="pplogger"}]
+[tool.poetry.dependencies]
+python = ">=3.10,<4.0"
+
+[tool.poetry.group.dev.dependencies]
+pytest = '*'
+pytest-cov = '*'
+ipython = '*'
+coverage = '*'
+pre-commit = '*'
+mypy = '*'
+ruff = '*'
+mkdocs = '*'
+mkdocs-material = '*'
+
+[tool.poetry.group.test.dependencies]
+pytest = "*"
+
+[build-system]
+requires = ["poetry-core>=1.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+src = ["pplogger", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.mypy]
+python_version = "3.10"
+files = ["pplogger"]
+warn_unused_ignores = true
+warn_redundant_casts = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+no_implicit_optional = true
+
+[tool.pytest.ini_options]
+addopts = "--cov=pplogger --cov-report=term-missing --cov-fail-under=85"
+testpaths = ["tests"]
+
+[tool.coverage.run]
+branch = true
+source = ["pplogger"]
+
+[tool.coverage.report]
+show_missing = true