fastlog-io 0.1.0__py3-none-any.whl

fastlog/__init__.py

@@ -0,0 +1,14 @@
+"""logs package – import‑time ready logger with Prometheus metrics helper.
+
+Public API:
+    configure            – reconfigure sinks, level, etc.
+    get_log(name=None)   – get bound logger
+    log                  – the global loguru log
+    start_metrics_server – start a Prometheus /metrics endpoint
+"""
+from .core import configure, get_log
+from .metrics import start_metrics_server
+
+__all__ = ['configure', 'get_log', 'log', 'start_metrics_server']
+
+log = get_log('app')

fastlog/config.py

@@ -0,0 +1,26 @@
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass
+class Config:
+    '''Holds runtime configuration for logging.'''
+
+    # Directory for log files. Defaults to None or $LOG_DIR env var
+    log_dir: Path | None = Path(os.getenv('LOG_DIR')) if os.getenv('LOG_DIR') else None
+    # Minimum log level. Can be overwritten with $LOG_LEVEL
+    level: str = os.getenv('LOG_LEVEL', 'INFO').upper()
+    # Loguru rotation policy (e.g. '100 MB' or '1 day').
+    rotation: str = os.getenv('LOG_ROTATION', '100 MB')
+    # Loguru retention policy (e.g. '30 days' or '10 files').
+    retention: str = os.getenv('LOG_RETENTION', '90 days')
+
+    format: str = (
+        '<green>{time:YYYY-MM-DD HH:mm:ss.SSS!UTC}</green> | '
+        '<level>{level:<8}</level> | '
+        '<yellow>{extra[name]:<5}</yellow> | '
+        '<light-black>{extra[trace_id]}</light-black> | '
+        '<cyan>{module}.{function}:{line}</cyan> | '
+        '<level>{message}</level>{exception}'
+    )

fastlog/core.py

@@ -0,0 +1,125 @@
+import sys
+from contextlib import contextmanager
+from functools import lru_cache
+from pathlib import Path
+from types import MethodType
+from typing import ContextManager, Iterator, cast
+
+from loguru import logger as _logger
+from loguru._logger import Logger as _Logger
+from loguru._logger import context as _context
+
+from .config import Config
+from .helpers import generate_id
+from .intercept import reset_std_logging
+from .metrics import metrics_patch
+
+__all__ = ['configure', 'get_log', 'trace_ctx']
+
+logger = _logger
+
+
+# --------------------------------------------------------------------------- #
+# Record patches
+# --------------------------------------------------------------------------- #
+
+
+def _patch_trace_and_name(record: dict) -> None:
+    trace_id = record['extra'].get('trace_id')
+    sub_trace_id = record['extra'].get('sub_trace_id')
+    if trace_id and sub_trace_id:
+        trace_id = f'{trace_id}:{sub_trace_id}'
+    elif sub_trace_id:
+        trace_id = sub_trace_id
+    elif not trace_id:
+        trace_id = f'-{generate_id(7)}'
+    record['extra']['trace_id'] = trace_id
+    record['extra'].setdefault('name', '-')
+
+
+# --------------------------------------------------------------------------- #
+# Trace Func
+# --------------------------------------------------------------------------- #
+
+
+@contextmanager
+def _trace_ctx(self: _Logger, trace_id: str | None = None) -> Iterator[None]:
+    trace_id = trace_id or generate_id(8)
+    if _context.get().get('trace_id'):
+        with self.contextualize(sub_trace_id=trace_id):
+            yield
+    else:
+        with self.contextualize(trace_id=trace_id):
+            yield
+
+
+_Logger.trace_ctx = MethodType(_trace_ctx, logger)
+
+
+# Add static type checking support
+class Logger(_Logger):
+    def trace_ctx(self, trace_id: str | None = None) -> ContextManager[None]: ...
+
+
+logger = cast(Logger, logger)
+
+
+# --------------------------------------------------------------------------- #
+# Config
+# --------------------------------------------------------------------------- #
+
+_configure: bool = False
+
+def configure(
+    log_dir: str | Path | None = None,
+    level: str | None = None,
+    rotation: str | None = None,
+    retention: str | None = None,
+) -> None:
+    cfg_kwargs = dict()
+    if log_dir is not None:
+        cfg_kwargs['log_dir'] = Path(log_dir)
+    if level is not None:
+        cfg_kwargs['level'] = level.upper()
+    if rotation is not None:
+        cfg_kwargs['rotation'] = rotation
+    if retention is not None:
+        cfg_kwargs['retention'] = retention
+
+    cfg = Config(**cfg_kwargs)
+
+    global logger
+
+    logger.remove()
+
+    logger = logger.patch(_patch_trace_and_name).patch(metrics_patch)
+
+    logger.add(
+        sys.stderr,
+        format=cfg.format,
+        level=cfg.level,
+        colorize=True,
+        enqueue=False,
+    )
+
+    if cfg.log_dir:
+        enqueue = sys.platform.startswith('linux')
+        logger.add(
+            cfg.log_dir / 'app.log',
+            format=cfg.format,
+            level=cfg.level,
+            rotation=cfg.rotation,
+            retention=cfg.retention,
+            enqueue=enqueue,
+        )
+
+    reset_std_logging()
+
+    global _configure
+    _configure = True
+
+@lru_cache
+def get_log(name: str | None = None):
+    if not _configure:
+        configure()
+    return logger.bind(name=name) if name else logger

fastlog/helpers.py

@@ -0,0 +1,11 @@
+import string
+
+from nanoid import generate
+
+__all__ = ['generate_id']
+
+
+def generate_id(size: int = 6, *, digits: bool = False) -> str:
+    '''Return a random NanoID (digits‑only when *digits* is True).'''
+    alphabet = string.digits if digits else string.ascii_letters + string.digits
+    return generate(alphabet, size=size)

fastlog/intercept.py

@@ -0,0 +1,47 @@
+import logging
+
+from loguru import logger
+
+from .helpers import generate_id
+class InterceptHandler(logging.Handler):
+    """ A handler that forwards standard logging records to Loguru. """
+
+    _cache: dict[str, str] = {}
+
+    def emit(self, record: logging.LogRecord) -> None:  # noqa: D401
+        try:
+            level = logger.level(record.levelname).name
+        except ValueError:
+            level = record.levelno
+
+        frame, depth = logging.currentframe(), 2
+        while frame and frame.f_code.co_filename == logging.__file__:
+            frame = frame.f_back  # type: ignore[assignment]
+            depth += 1
+
+        logger.opt(depth=depth, exception=record.exc_info).bind(
+            action=f'[{record.name}]{record.module}.{record.funcName}:{record.lineno}',
+            trace_id=self._track_id(record.name),
+        ).log(level, record.getMessage())
+
+    @classmethod
+    def _track_id(cls, name: str) -> str:
+        if name not in cls._cache:
+            cls._cache[name] = f'-{generate_id(6, digits=True)}-'
+        return cls._cache[name]
+
+
+def reset_std_logging() -> None:
+    """ Replace the root logger's handlers with a single `InterceptHandler`. """
+    root = logging.getLogger()
+    root.handlers.clear()
+    root.addHandler(InterceptHandler())
+    root.setLevel(logging.WARNING)
+
+
+def reset_uvicorn_logging() -> None:
+    # Capture the uvicorn log correctly to prevent duplicate output
+    for name in ('uvicorn', 'uvicorn.error', 'uvicorn.access'):
+        logging.getLogger(name).handlers.clear()
+        logging.getLogger(name).propagate = False
+    logging.getLogger('uvicorn').handlers = [InterceptHandler()]

fastlog/metrics.py

@@ -0,0 +1,33 @@
+"""Prometheus metrics integration for logs package.
+
+Expose counters to let Grafana/Prometheus track log volume by level and logger name.
+"""
+try:
+    from prometheus_client import Counter, start_http_server
+
+    LOG_COUNTER = Counter(
+        'log_messages_total',
+        'Total log messages',
+        labelnames=('level', 'name'),
+    )
+except ImportError:  # pragma: no cover – optional dependency
+    LOG_COUNTER = None
+    Counter = None
+
+__all__ = ['start_metrics_server', 'metrics_patch']
+
+
+def metrics_patch(record: dict) -> None:
+    '''Loguru patch: increment Prometheus counter for each record.'''
+    if LOG_COUNTER is None:
+        return
+    level = record['level'].name.lower()
+    name = record['extra'].get('name', '-')
+    LOG_COUNTER.labels(level, name).inc()
+
+
+def start_metrics_server(port: int = 8000):
+    '''Start a background HTTP server on *port* exposing /metrics.'''
+    if Counter is None:
+        raise RuntimeError('prometheus_client is not installed')
+    start_http_server(port)

fastlog_io-0.1.0.dist-info/METADATA

@@ -0,0 +1,144 @@
+Metadata-Version: 2.4
+Name: fastlog-io
+Version: 0.1.0
+Summary: Thin wrapper around loguru with Prometheus metrics
+Author: owq
+License: MIT License
+License-File: LICENSE
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Topic :: System :: Logging
+Requires-Python: >=3.10
+Requires-Dist: loguru>=0.7.3
+Requires-Dist: nanoid>=2.0.0
+Provides-Extra: metrics
+Requires-Dist: prometheus-client>=0.22.1; extra == 'metrics'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <a href="https://pypi.org/project/fastlog-io" target="_blank">
+  <img src="https://img.owq.world/2025/fastlog-logo-857f7d.png" alt="FastLOG">
+  </a>
+</p>
+<p align="center">
+    <em>FastLOG is a lightweight wrapper around <a href="https://github.com/Delgan/loguru" target="_blank">Loguru</a> that offers Prometheus metrics, automatic `trace_id`, colourful output, and a dead‑simple configuration API.</em>
+</p>
+<p align="center">
+  <a href="https://pypi.org/project/fastlog-io" target="_blank">
+      <img src="https://img.shields.io/pypi/v/fastlog-io" alt="Package version">
+  </a>
+  <span> | <span>
+  <a href="https://pypi.org/project/fastlog-io" target="_blank">
+      <img src="https://img.shields.io/pypi/status/fastlog-io" alt="Development Status">
+  </a>
+  <span> | <span>
+  <a href="https://pypi.org/project/fastlog-io" target="_blank">
+      <img src="https://img.shields.io/pypi/pyversions/fastlog-io" alt="Supported Python versions">
+  </a>
+</p>
+
+
+---
+
+## ✨ Features
+
+* **Zero‑config out of the box** – `from fastlog-io import log; log.info("hello")` works instantly.
+* **Unified interface** – `configure()` + `get_log(name)` keep formatting consistent across modules.
+* **Automatic `trace_id`** – generates a 7‑char NanoID when none is bound, perfect for request tracing.
+* **Prometheus ready** – one call to `start_metrics_server()` exposes `/metrics` with log counters.
+* **File rotation & retention** – default `rotation="100 MB"`; tune it via `configure()`.
+* **Stdlib compatibility** – built‑in `reset_std_logging()` redirects the `logging` module to fastlog-io.
+
+---
+
+## 🚀 Installation
+
+```bash
+pip install fastlog-io
+# Use the prometheus dependency version
+pip install fastlog-io[metrics]
+```
+
+**Requirements**
+
+* Python ≥ 3.12
+* [loguru](https://pypi.org/project/loguru/)
+* Optional: [prometheus‑client](https://pypi.org/project/prometheus-client/) for metric export
+
+---
+
+## ⚡ Quickstart
+
+```python
+from fastlog import log, configure, start_metrics_server
+
+# override defaults if needed
+configure(level="DEBUG", log_dir="./logs")
+start_metrics_server(port=9100)
+
+log.info("service started")
+
+# child logger
+api_log = log.bind(name="api")
+api_log.debug("new request")
+```
+
+Console output (colours stripped):
+
+```
+2025-06-21 09:57:56.510 | INFO     | app   | -cFZrY2V | main.<module>:7 | service started
+2025-06-21 09:57:56.511 | DEBUG    | api   | -25bJVku | main.<module>:11 | new request
+```
+
+---
+
+## 🔧 Environment variables
+
+| Variable       | Default   | Description                                           |
+| -------------- | --------- | ----------------------------------------------------- |
+| `LOG_DIR`      | *(empty)* | Log file directory; leave blank to log to stderr only |
+| `LOG_LEVEL`    | `INFO`    | Minimum log level                                     |
+| `LOG_ROTATION` | `100 MB`  | File rotation policy (Loguru syntax)                  |
+
+> These can also be passed directly to `configure()` and override environment values.
+
+---
+
+## 📊 Metrics
+
+* **`log_messages_total{level, name}`** – total log messages, labelled by level and logger name.
+
+Prometheus scrape example:
+
+```yaml
+targets:
+  - job_name: fastlog-io
+    static_configs:
+      - targets: ["127.0.0.1:9100"]
+```
+
+---
+
+## 🛠 Development & Tests (powered by [uv](https://github.com/astral-sh/uv))
+
+```bash
+# run tests in a temp venv with test extras installed
+uv run --with '.[test]' pytest -q
+
+# build wheel + sdist
+uv build
+
+# verify the built wheel in a clean env
+uv run --with dist/*.whl --with pytest pytest -q
+```
+
+---
+
+## 📄 License
+
+[MIT](LICENSE) © 2025 OWQ

fastlog_io-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+fastlog/__init__.py,sha256=liEBajqZD3wmqILPpAbfVZ1xyn4vLvy5LG5SOeMfAjo,487
+fastlog/config.py,sha256=9PKil_bQxk_Y4KhL_6sdRf3HIDEECR4lfqm2RFCv-NE,987
+fastlog/core.py,sha256=vZR6tJq8N68vtAxLdUtVvAFyjmiUZmWya0BP-Ud6_Og,3345
+fastlog/helpers.py,sha256=ywzfhMFD1uiyXrIvZX9FTgT0y39QX6HvJGo-WfZeaMw,330
+fastlog/intercept.py,sha256=rf9BbRWvAJ2Z6whqsLRXnzPq2l4zHDwA-mtTQ8pEdNY,1649
+fastlog/metrics.py,sha256=g3_hA7m5jVI6scGOGC5fo9Yb71BugL8km-V9SNQa-r8,1015
+fastlog_io-0.1.0.dist-info/METADATA,sha256=dS5JHTmhduI-zDV-4FqeWIGmc2EojIn6bdeO8HTpjOM,4427
+fastlog_io-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+fastlog_io-0.1.0.dist-info/licenses/LICENSE,sha256=H5l4pEKXYzeobqnqWgyXrmsb2rVtlmHQWTjxY7jlW-M,1055
+fastlog_io-0.1.0.dist-info/RECORD,,

fastlog_io-0.1.0.dist-info/WHEEL

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

fastlog_io-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2017
+
+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.