xakki-log-python 0.4.0__py3-none-any.whl

log_python/__init__.py

@@ -0,0 +1,160 @@
+"""xakki-log-python — structured logging library for Python.
+
+GELF/Graylog-oriented, Python port of xakki/laralog (PHP/Laravel).
+
+Includes the shared field/type contract, redaction, enrichment, trace capture,
+wire formatters, explicit stdlib ``logging`` setup, scoped context and optional
+Redis/SQLAlchemy integrations.
+"""
+
+import logging
+from typing import TextIO
+
+from log_python.config import ExtraConfig, PylogConfig, TraceConfig, TraceDepthConfig
+from log_python.const import (
+    LOGGER_COUNT,
+    LOGGER_MCTIME,
+    LOGGER_MEMORY,
+    LOGGER_MEMORY_PEAK,
+    LOGGER_MONITORING,
+    LOGGER_SKIP_TRACE,
+    LOGGER_STATUS,
+    LOGGER_SUCCESS,
+    LOGGER_SUM,
+    LOGGER_TAG,
+    LOGGER_TIME,
+    LOGGER_VER,
+)
+from log_python.context import (
+    CONTEXT_FALSE_VALUES,
+    CONTEXT_MAX_STRING_BYTES,
+    CONTEXT_TYPE_BOOL,
+    CONTEXT_TYPE_FLOAT,
+    CONTEXT_TYPE_INT,
+    CONTEXT_TYPE_SKIP,
+    CONTEXT_TYPE_STRING,
+    ContextTypeCorrector,
+    bind,
+    bound_context,
+    clear,
+    get_bound_context,
+    remote_ip,
+)
+from log_python.formatters import ConsoleFormatter, ExtraFilter, JsonFormatter, LineFormatter, trim_log
+from log_python.heartbeat import Heartbeat
+from log_python.logtype import LogType, handlers_installed, install_handlers, uninstall_handlers
+from log_python.manager import (
+    EXCEPTION_CHAIN_FIELD,
+    LogManager,
+    get_or_create_request_id,
+    reset_request_id,
+    set_request_id,
+)
+from log_python.redactor import BUILTIN_NEEDLES, MASK, Redactor
+from log_python.trace import CapturedTrace, TraceCapture, exception_class_name, exception_origin, should_skip_trace
+
+__version__ = LOGGER_VER
+
+_SETUP_HANDLER: logging.Handler | None = None
+
+
+class _PylogStreamHandler(logging.StreamHandler[TextIO]):
+    _pylog_handler = True
+
+
+def setup(
+    *,
+    config: PylogConfig | None = None,
+    level: int = logging.INFO,
+    stream: TextIO | None = None,
+    formatter: str | logging.Formatter = "json",
+    replace: bool = False,
+) -> logging.Handler:
+    """Configure one idempotent structured handler on the root logger."""
+    global _SETUP_HANDLER
+    resolved = config or PylogConfig.from_env()
+    root = logging.getLogger()
+    if _SETUP_HANDLER is not None and _SETUP_HANDLER in root.handlers and not replace:
+        return _SETUP_HANDLER
+    if _SETUP_HANDLER is not None:
+        root.removeHandler(_SETUP_HANDLER)
+    handler = _PylogStreamHandler(stream)
+    handler.terminator = ""
+    handler.setLevel(level)
+    handler.addFilter(ExtraFilter(resolved))
+    if isinstance(formatter, logging.Formatter):
+        selected = formatter
+    elif formatter == "json":
+        selected = JsonFormatter(resolved)
+    elif formatter == "line":
+        selected = LineFormatter(resolved)
+    elif formatter == "console":
+        selected = ConsoleFormatter(resolved)
+    else:
+        raise ValueError(f"Unknown pylog formatter: {formatter!r}")
+    handler.setFormatter(selected)
+    root.addHandler(handler)
+    if root.level == logging.NOTSET or root.level > level:
+        root.setLevel(level)
+    _SETUP_HANDLER = handler
+    if resolved.capture_handlers:
+        install_handlers()
+    return handler
+
+
+__all__ = [
+    "BUILTIN_NEEDLES",
+    "CONTEXT_FALSE_VALUES",
+    "CONTEXT_MAX_STRING_BYTES",
+    "CONTEXT_TYPE_BOOL",
+    "CONTEXT_TYPE_FLOAT",
+    "CONTEXT_TYPE_INT",
+    "CONTEXT_TYPE_SKIP",
+    "CONTEXT_TYPE_STRING",
+    "EXCEPTION_CHAIN_FIELD",
+    "LOGGER_COUNT",
+    "LOGGER_MCTIME",
+    "LOGGER_MEMORY",
+    "LOGGER_MEMORY_PEAK",
+    "LOGGER_MONITORING",
+    "LOGGER_SKIP_TRACE",
+    "LOGGER_STATUS",
+    "LOGGER_SUCCESS",
+    "LOGGER_SUM",
+    "LOGGER_TAG",
+    "LOGGER_TIME",
+    "LOGGER_VER",
+    "MASK",
+    "CapturedTrace",
+    "ConsoleFormatter",
+    "ContextTypeCorrector",
+    "ExtraConfig",
+    "ExtraFilter",
+    "Heartbeat",
+    "JsonFormatter",
+    "LineFormatter",
+    "LogManager",
+    "LogType",
+    "PylogConfig",
+    "Redactor",
+    "TraceCapture",
+    "TraceConfig",
+    "TraceDepthConfig",
+    "__version__",
+    "bind",
+    "bound_context",
+    "clear",
+    "exception_class_name",
+    "exception_origin",
+    "get_bound_context",
+    "get_or_create_request_id",
+    "handlers_installed",
+    "install_handlers",
+    "remote_ip",
+    "reset_request_id",
+    "set_request_id",
+    "setup",
+    "should_skip_trace",
+    "trim_log",
+    "uninstall_handlers",
+]

log_python/config.py

@@ -0,0 +1,144 @@
+"""Runtime configuration ported from the reference `config/logger.php`.
+
+The PHP original reads `env()` at config-definition time on purpose (its
+comment: values are captured by `php artisan config:cache`, so they survive
+into production, unlike an `env()` call from runtime code once the cache is
+warm). The Python equivalent hazard is `os.environ` mutation after startup;
+`PylogConfig.from_env()` mirrors the intent by taking a single snapshot at
+construction time via an explicitly injectable mapping, so tests never need
+to mutate the real process environment.
+
+Every config object here is a frozen dataclass: build one at process start
+and pass it around, never mutate it. `redact` and `context_type_rules` are
+merge-on-top overrides consumed by later phases (Redactor, context type
+coercion respectively) — they default to empty here.
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from types import MappingProxyType
+
+from log_python.const import LOGGER_VER
+
+_TRUE_VALUES = frozenset({"1", "true", "yes", "on"})
+_FALSE_VALUES = frozenset({"0", "false", "no", "off", ""})
+
+# Python-side substitution for the PHP `excluded_partials` default
+# (`Monolog`, `Illuminate/Log/`, `vendor/`) — see mapping.md.
+_DEFAULT_EXCLUDED_PARTIALS: tuple[str, ...] = ("logging/", "site-packages/", "log_python/")
+
+_EMPTY_CONTEXT_TYPE_RULES: Mapping[str, Mapping[str, str]] = MappingProxyType({})
+
+
+def _parse_bool(env: Mapping[str, str], key: str, default: bool) -> bool:
+    """Parse a boolean env var.
+
+    Accepts (case-insensitive) ``1``/``true``/``yes``/``on`` as True and
+    ``0``/``false``/``no``/``off``/empty-string as False. Any other value
+    raises ``ValueError`` naming the offending variable.
+    """
+    if key not in env:
+        return default
+    raw = env[key].strip().lower()
+    if raw in _TRUE_VALUES:
+        return True
+    if raw in _FALSE_VALUES:
+        return False
+    raise ValueError(f"Environment variable {key!r} is not a valid boolean: {env[key]!r}")
+
+
+def _parse_int(env: Mapping[str, str], key: str, default: int) -> int:
+    """Parse an integer env var, raising ``ValueError`` naming the variable on non-integer input."""
+    if key not in env:
+        return default
+    raw = env[key].strip()
+    try:
+        return int(raw)
+    except ValueError as exc:
+        raise ValueError(f"Environment variable {key!r} is not a valid integer: {env[key]!r}") from exc
+
+
+def _parse_optional_str(env: Mapping[str, str], key: str) -> str | None:
+    """Return the raw env var value, or None when unset (mirrors PHP `env()`)."""
+    return env.get(key)
+
+
+@dataclass(frozen=True, slots=True)
+class ExtraConfig:
+    """Stable-per-process fields dumped onto every record (spec §4.2 extra)."""
+
+    app_name: str | None = None
+    app_env: str | None = None
+    app_ver: str | None = None
+    log_ver: str = LOGGER_VER
+    tier: str | None = None
+    release_tag: str | None = None
+    release_time: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class TraceDepthConfig:
+    """Trace depth (frames captured) per severity level."""
+
+    warning: int = 5
+    error: int = 10
+    critical: int = 20  # also alert / emergency
+
+
+@dataclass(frozen=True, slots=True)
+class TraceConfig:
+    """Stack trace capture settings (spec §3.7 / §4.6)."""
+
+    excluded_partials: tuple[str, ...] = _DEFAULT_EXCLUDED_PARTIALS
+    depth: TraceDepthConfig = field(default_factory=TraceDepthConfig)
+    arg_limit: int = 128
+
+
+@dataclass(frozen=True, slots=True)
+class PylogConfig:
+    """Top-level configuration, ported 1:1 (keys and defaults) from `config/logger.php`."""
+
+    message_limit: int = 3024
+    allow_memory: bool = False
+    extra: ExtraConfig = field(default_factory=ExtraConfig)
+    trace: TraceConfig = field(default_factory=TraceConfig)
+    # Extra redaction needles, merged on top of the Redactor built-ins (phase 2).
+    redact: tuple[str, ...] = ()
+    snake_case: bool = False
+    # Project overrides merged on top of the context type-coercion table (phase 3).
+    context_type_rules: Mapping[str, Mapping[str, str]] = field(default_factory=lambda: _EMPTY_CONTEXT_TYPE_RULES)
+    capture_handlers: bool = False
+
+    @classmethod
+    def from_env(cls, env: Mapping[str, str] | None = None) -> PylogConfig:
+        """Build a config snapshot from environment variables, read exactly once.
+
+        `env` defaults to `os.environ`; pass an explicit mapping (e.g. in
+        tests) so the real process environment is never touched.
+        """
+        resolved_env: Mapping[str, str] = os.environ if env is None else env
+
+        extra = ExtraConfig(
+            app_name=_parse_optional_str(resolved_env, "APP_NAME"),
+            app_env=_parse_optional_str(resolved_env, "APP_ENV"),
+            app_ver=_parse_optional_str(resolved_env, "APP_VERSION"),
+            # log_ver is a compile-time constant in the reference, not env()-backed.
+            log_ver=LOGGER_VER,
+            tier=_parse_optional_str(resolved_env, "LOG_TIER"),
+            release_tag=_parse_optional_str(resolved_env, "RELEASE_TAG"),
+            release_time=_parse_optional_str(resolved_env, "RELEASE_TIME"),
+        )
+
+        return cls(
+            message_limit=_parse_int(resolved_env, "LOG_MESSAGE_LIMIT", 3024),
+            allow_memory=_parse_bool(resolved_env, "LOG_ALLOW_MEMORY", default=False),
+            extra=extra,
+            trace=TraceConfig(),
+            redact=(),
+            snake_case=_parse_bool(resolved_env, "LOG_SNAKE_CASE", default=False),
+            context_type_rules=_EMPTY_CONTEXT_TYPE_RULES,
+            capture_handlers=_parse_bool(resolved_env, "LOG_CAPTURE_HANDLERS", default=False),
+        )

log_python/const.py

@@ -0,0 +1,41 @@
+"""Field-name contract ported from the reference `src/const.php`.
+
+Each ``LOGGER_*`` constant is a context/record field NAME (a dict key), not a
+value — they must stay byte-for-byte identical to the PHP reference so a
+mixed PHP/Python fleet emits the same field names on the wire.
+
+``LOGGER_VER`` is the odd one out: it is the installed library version stamped
+into the ``log_ver`` extra field (see ``config.ExtraConfig.log_ver``). It is
+read from standard distribution metadata generated from ``pyproject.toml``;
+``log_python.__version__`` aliases it, so releases have one authoritative version
+declaration compatible with Hatchling, Poetry, PDM, Pipenv and pip.
+
+PHP's ``DS`` (``DIRECTORY_SEPARATOR``) constant is PHP-only cruft and is
+deliberately not ported.
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+from typing import Final
+
+
+def _package_version() -> str:
+    try:
+        return version("xakki-log-python")
+    except PackageNotFoundError:
+        # Source-tree fallback for tools that import without installing the project.
+        return "0+unknown"
+
+
+LOGGER_VER: Final[str] = _package_version()
+
+LOGGER_TIME: Final[str] = "time"
+LOGGER_MCTIME: Final[str] = "mctime"  # float seconds, e.g. 1.000001
+LOGGER_MONITORING: Final[str] = "monitoring"
+LOGGER_STATUS: Final[str] = "status"
+LOGGER_COUNT: Final[str] = "count"
+LOGGER_SUM: Final[str] = "sum"
+LOGGER_MEMORY: Final[str] = "memory_usage"
+LOGGER_MEMORY_PEAK: Final[str] = "memory_peak"
+LOGGER_TAG: Final[str] = "tag"
+LOGGER_SUCCESS: Final[str] = "success"
+LOGGER_SKIP_TRACE: Final[str] = "skipTrace"