instruktai-python-logger 0.4.5__tar.gz → 0.5.1__tar.gz

{instruktai_python_logger-0.4.5 → instruktai_python_logger-0.5.1}/PKG-INFO

@@ -1,12 +1,9 @@
 Metadata-Version: 2.4
 Name: instruktai-python-logger
-Version: 0.4.5
+Version: 0.5.1
 Summary: Centralized logging utilities for Python services.
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
-Provides-Extra: dev
-Requires-Dist: pytest>=8; extra == "dev"
-Requires-Dist: ruff>=0.8; extra == "dev"
 
 # InstruktAI Python Logger
 
@@ -22,7 +19,7 @@ Publishing notes live in `docs/publishing.md`.
 From PyPI (recommended):
 
 ```bash
-pip install instrukt-ai-logger
+pip install instruktai-python-logger
 ```
 
 From GitHub:

{instruktai_python_logger-0.4.5 → instruktai_python_logger-0.5.1}/README.md

@@ -12,7 +12,7 @@ Publishing notes live in `docs/publishing.md`.
 From PyPI (recommended):
 
 ```bash
-pip install instrukt-ai-logger
+pip install instruktai-python-logger
 ```
 
 From GitHub:

{instruktai_python_logger-0.4.5 → instruktai_python_logger-0.5.1}/instrukt_ai_logging/__init__.py

@@ -4,30 +4,31 @@ See `README.md` for usage and `docs/design.md` for design intent.
 """
 
 __all__ = [
+    "TRACE",
+    "InstruktAILogger",
+    "InstruktAILoggerProtocol",
     "__version__",
     "configure_logging",
     "get_logger",
-    "InstruktAILogger",
-    "InstruktAILoggerProtocol",
     "resolve_log_file",
     "resolve_log_files",
-    "TRACE",
 ]
 
 try:
-    from importlib.metadata import packages_distributions, version as _pkg_version
+    from importlib.metadata import packages_distributions
+    from importlib.metadata import version as _pkg_version
 
     _dists = packages_distributions().get(__name__, [])
     __version__ = _pkg_version(_dists[0]) if _dists else "0.0.0"
 except Exception:  # pragma: no cover
     __version__ = "0.0.0"
 
-from instrukt_ai_logging.logging import (  # noqa: E402  (intentional re-export)
-    configure_logging,
-    get_logger,
+from instrukt_ai_logging.logging import (
+    TRACE,
     InstruktAILogger,
     InstruktAILoggerProtocol,
+    configure_logging,
+    get_logger,
     resolve_log_file,
     resolve_log_files,
-    TRACE,
 )

{instruktai_python_logger-0.4.5 → instruktai_python_logger-0.5.1}/instrukt_ai_logging/cli.py

@@ -6,8 +6,8 @@ import re
 import sys
 import threading
 import time
+from collections.abc import Iterator
 from pathlib import Path
-from typing import Iterator
 
 from instrukt_ai_logging.logging import (
     iter_recent_log_lines_merged,
@@ -102,6 +102,15 @@ def _parse_stems(value: str) -> list[str]:
     return [item.strip() for item in value.split(",") if item.strip()]
 
 
+def _line_passes(line: str, *, keep: re.Pattern[str] | None, drop: re.Pattern[str] | None) -> bool:
+    """Apply the inclusive `--grep` keep filter then the `--exclude` drop filter."""
+    if keep is not None and not keep.search(line):
+        return False
+    if drop is not None and drop.search(line):
+        return False
+    return True
+
+
 def _stem_of(path: Path) -> str:
     """Return the stem before the first `.log` suffix (e.g. `cron.log.1` → `cron`)."""
     name = path.name
@@ -116,6 +125,64 @@ def _is_rotation_suffix(path: Path) -> bool:
     return idx > 0 and name[idx + len(".log") :] != ""
 
 
+def _follow_files(
+    files: list[Path],
+    stems: list[str] | None,
+    *,
+    keep: re.Pattern[str] | None,
+    drop: re.Pattern[str] | None,
+) -> None:
+    """Follow each selected file concurrently, applying the keep/drop filters.
+
+    New lines from any file are written to stdout as they arrive — no cross-file
+    timestamp merge in follow mode, since real-time arrival ordering is its own
+    merge. For the explicit `--logs`/`--include` case, follow each named stem's
+    canonical `<stem>.log` so we don't follow rotated history.
+    """
+    follow_files: list[Path]
+    if stems is None:
+        follow_files = [p for p in files if not _is_rotation_suffix(p)]
+    else:
+        follow_files = []
+        for stem in stems:
+            for p in files:
+                if p.name == f"{stem}.log":
+                    follow_files.append(p)
+                    break
+
+    if not follow_files:
+        return
+
+    stop_event = threading.Event()
+
+    def _follow_one(path: Path) -> None:
+        try:
+            for line in iter_follow_lines(path, start_at_end=True):
+                if stop_event.is_set():
+                    return
+                if not _line_passes(line, keep=keep, drop=drop):
+                    continue
+                sys.stdout.write(line)
+                sys.stdout.flush()
+        except OSError:
+            return
+
+    threads = [
+        threading.Thread(target=_follow_one, args=(path,), daemon=True, name=f"follow-{path.name}")
+        for path in follow_files
+    ]
+    for t in threads:
+        t.start()
+
+    try:
+        while any(t.is_alive() for t in threads):
+            for t in threads:
+                t.join(timeout=0.25)
+    except KeyboardInterrupt:
+        stop_event.set()
+        return
+
+
 def main() -> None:
     from instrukt_ai_logging import __version__
 
@@ -126,22 +193,26 @@ def main() -> None:
         version=f"%(prog)s {__version__}",
     )
     parser.add_argument("app", help="App/service name (folder under /var/log/instrukt-ai/)")
-    parser.add_argument(
-        "--since", default="10m", help="Time window (e.g. 10m, 2h, 1d). Default: 10m"
-    )
+    parser.add_argument("--since", default="10m", help="Time window (e.g. 10m, 2h, 1d). Default: 10m")
     parser.add_argument(
         "-f",
         "--follow",
         action="store_true",
         help="Follow the log (tail -f style) after printing the --since window",
     )
-    parser.add_argument("--grep", default="", help="Regex to filter lines (optional)")
+    parser.add_argument("--grep", default="", help="Regex to keep only matching lines (optional)")
+    parser.add_argument(
+        "--exclude",
+        default="",
+        help="Regex to drop matching lines (applied after --grep; optional)",
+    )
     parser.add_argument(
         "--logs",
+        "--include",
         default="",
         help=(
             "Comma-separated list of stems to include (e.g. 'cron,docs-watch'). "
-            "Default: all log files in the app's directory."
+            "Default: all log files in the app's directory. Alias: --include."
         ),
     )
     args = parser.parse_args()
@@ -152,6 +223,7 @@ def main() -> None:
         raise SystemExit(str(e)) from e
 
     pattern = re.compile(args.grep) if args.grep else None
+    exclude_pattern = re.compile(args.exclude) if args.exclude else None
     stems = _parse_stems(args.logs) or None
 
     files = resolve_log_files(args.app, stems=stems)
@@ -159,66 +231,15 @@ def main() -> None:
         if stems:
             available = sorted({_stem_of(p) for p in resolve_log_files(args.app)})
             available_str = ", ".join(available) if available else "(none)"
-            raise SystemExit(
-                f"No log files matched stems {stems} in app '{args.app}'. "
-                f"Available: {available_str}"
-            )
+            raise SystemExit(f"No log files matched stems {stems} in app '{args.app}'. Available: {available_str}")
         raise SystemExit(f"No log files found for app '{args.app}'")
 
     for line in iter_recent_log_lines_merged(files, since):
-        if pattern and not pattern.search(line):
-            continue
-        sys.stdout.write(line)
+        if _line_passes(line, keep=pattern, drop=exclude_pattern):
+            sys.stdout.write(line)
 
     if not args.follow:
         return
 
     sys.stdout.flush()
-
-    # Follow each selected file concurrently. New lines from any file are
-    # written to stdout as they arrive — no cross-file timestamp merge in
-    # follow mode, since real-time arrival ordering is its own merge.
-    # Filter to files that actually exist for the canonical (default) glob —
-    # for the explicit `--logs=` case, follow each named stem's canonical
-    # file (the unsuffixed `<stem>.log`) so we don't follow rotated history.
-    if stems is None:
-        follow_files = [p for p in files if not _is_rotation_suffix(p)]
-    else:
-        follow_files = []
-        for stem in stems:
-            for p in files:
-                if p.name == f"{stem}.log":
-                    follow_files.append(p)
-                    break
-
-    if not follow_files:
-        return
-
-    stop_event = threading.Event()
-
-    def _follow_one(path: Path) -> None:
-        try:
-            for line in iter_follow_lines(path, start_at_end=True):
-                if stop_event.is_set():
-                    return
-                if pattern and not pattern.search(line):
-                    continue
-                sys.stdout.write(line)
-                sys.stdout.flush()
-        except OSError:
-            return
-
-    threads = [
-        threading.Thread(target=_follow_one, args=(path,), daemon=True, name=f"follow-{path.name}")
-        for path in follow_files
-    ]
-    for t in threads:
-        t.start()
-
-    try:
-        while any(t.is_alive() for t in threads):
-            for t in threads:
-                t.join(timeout=0.25)
-    except KeyboardInterrupt:
-        stop_event.set()
-        return
+    _follow_files(files, stems, keep=pattern, drop=exclude_pattern)

{instruktai_python_logger-0.4.5 → instruktai_python_logger-0.5.1}/instrukt_ai_logging/install.py

@@ -7,6 +7,9 @@ import os
 import sys
 from pathlib import Path
 
+DEFAULT_NEWSYSLOG_CONF = Path("/etc/newsyslog.d/instrukt-ai.conf")
+DEFAULT_LOGROTATE_CONF = Path("/etc/logrotate.d/instrukt-ai")
+
 
 def _write_file(path: Path, content: str, *, force: bool) -> None:
     if path.exists() and not force:
@@ -15,24 +18,47 @@ def _write_file(path: Path, content: str, *, force: bool) -> None:
     path.write_text(content, encoding="utf-8")
 
 
-def _install_newsyslog(log_root: Path, *, force: bool) -> Path:
-    """Install a glob-based newsyslog rule covering every app's *.log file.
+def _install_newsyslog(
+    log_root: Path,
+    *,
+    force: bool,
+    conf_path: Path = DEFAULT_NEWSYSLOG_CONF,
+) -> Path:
+    """Install newsyslog rules covering every app's *.log file.
 
     Format: path  owner:group  mode  count  size(KB)  when  flags
     Defaults: 50 MB rotation, 5 archives, gzip-compress archives (Z flag).
+
+    macOS newsyslog requires literal filenames — its config does NOT
+    expand globs at runtime. We therefore enumerate every existing
+    *.log file under log_root and emit one explicit line per file.
+    Re-run `instrukt-ai-log-setup --force` after a new producer creates
+    its first log file (which can be wired into the app's installer or
+    a daemon's periodic cleanup task).
     """
-    conf_path = Path("/etc/newsyslog.d/instrukt-ai.conf")
-    line = f"{log_root}/" + "*/*.log  640  5  50000  *  Z\n"
-    _write_file(conf_path, line, force=force)
+    if log_root.is_dir():
+        log_files = sorted(p for p in log_root.glob("*/*.log") if p.is_file())
+    else:
+        log_files = []
+    lines = "".join(f"{path}  640  5  50000  *  Z\n" for path in log_files)
+    if not lines:
+        # No log files yet — write a placeholder comment so the conf is
+        # discoverable on disk for future re-runs.
+        lines = f"# instrukt-ai-log-setup: no *.log files found under {log_root}\n"
+    _write_file(conf_path, lines, force=force)
     return conf_path
 
 
-def _install_logrotate(log_root: Path, *, force: bool) -> Path:
+def _install_logrotate(
+    log_root: Path,
+    *,
+    force: bool,
+    conf_path: Path = DEFAULT_LOGROTATE_CONF,
+) -> Path:
     """Install a glob-based logrotate rule covering every app's *.log file.
 
     Defaults: 50 MB rotation, 5 archives, gzip-compress archives.
     """
-    conf_path = Path("/etc/logrotate.d/instrukt-ai")
     content = f"""{log_root}/*/*.log {{
     size 50M
     rotate 5

{instruktai_python_logger-0.4.5 → instruktai_python_logger-0.5.1}/instrukt_ai_logging/logging.py

@@ -4,17 +4,18 @@ import heapq
 import logging
 import os
 import re
+from collections.abc import Iterable, Iterator
 from dataclasses import dataclass
-from datetime import datetime, timedelta, timezone
+from datetime import UTC, datetime, timedelta
 from logging.handlers import WatchedFileHandler
 from pathlib import Path
-from typing import Any, Iterable, Iterator, Protocol, cast, runtime_checkable
+from typing import Any, Protocol, cast, runtime_checkable
 
 # Standard logging levels are: NOTSET=0, DEBUG=10, INFO=20, WARNING=30, ERROR=40, CRITICAL=50
 TRACE: int = 5
 logging.addLevelName(TRACE, "TRACE")
 # Monkey-patch logging so our _level_name_to_int helper finds it automatically.
-setattr(logging, "TRACE", TRACE)
+logging.TRACE = TRACE  # type: ignore[attr-defined]
 
 
 def _normalize_env_prefix(name: str) -> str:
@@ -68,12 +69,12 @@ def _parse_csv(value: str) -> list[str]:
 
 
 def _now_utc() -> datetime:
-    return datetime.now(tz=timezone.utc)
+    return datetime.now(tz=UTC)
 
 
 class UtcMillisFormatter(logging.Formatter):
     def formatTime(self, record: logging.LogRecord, datefmt: str | None = None) -> str:
-        dt = datetime.fromtimestamp(record.created, tz=timezone.utc)
+        dt = datetime.fromtimestamp(record.created, tz=UTC)
         if datefmt:
             return dt.strftime(datefmt)
         return dt.strftime("%Y-%m-%dT%H:%M:%S") + f".{int(record.msecs):03d}Z"
@@ -161,18 +162,17 @@ class LogfmtFormatter(UtcMillisFormatter):
             f"msg={_format_logfmt_string(str(message), max_chars=self.max_message_chars, force_quote=True)}",
         ]
 
-        kv: object = getattr(record, "kv", None)
-        if isinstance(kv, dict):
-            for key in sorted(kv.keys(), key=lambda x: str(x)):
+        raw_kv: object = getattr(record, "kv", None)
+        if isinstance(raw_kv, dict):
+            kv = cast("dict[object, object]", raw_kv)
+            for key in sorted(kv.keys(), key=lambda k: str(k)):
                 if key == "msg":
                     continue
                 if not isinstance(key, str):
                     continue
                 if not _SAFE_KEY.fullmatch(key):
                     continue
-                parts.append(
-                    f"{key}={_format_logfmt_value(kv[key], max_chars=self.max_message_chars)}"
-                )
+                parts.append(f"{key}={_format_logfmt_value(kv[key], max_chars=self.max_message_chars)}")
 
         if record.exc_info:
             try:
@@ -216,9 +216,7 @@ class InstruktAILogger(logging.Logger):
     All `**kv` values are serialized to text by the formatter.
     """
 
-    def _log_with_kv(
-        self, level: int, msg: object, args: tuple[object, ...], **kwargs: Any
-    ) -> None:
+    def _log_with_kv(self, level: int, msg: object, args: tuple[object, ...], **kwargs: Any) -> None:
         exc_info = kwargs.pop("exc_info", None)
         stack_info = kwargs.pop("stack_info", False)
         stacklevel = kwargs.pop("stacklevel", 1)
@@ -229,7 +227,7 @@ class InstruktAILogger(logging.Logger):
 
         merged_extra: dict[str, object] = {}
         if isinstance(extra, dict):
-            merged_extra.update(extra)
+            merged_extra.update(cast("dict[str, object]", extra))
 
         existing_kv = merged_extra.get("kv")
         if isinstance(existing_kv, dict):
@@ -251,33 +249,33 @@ class InstruktAILogger(logging.Logger):
         if self.isEnabledFor(TRACE):
             self._log_with_kv(TRACE, msg, args, **kwargs)
 
-    def debug(self, msg: object, *args: object, **kwargs: Any) -> None:  # type: ignore[override]
+    def debug(self, msg: object, *args: object, **kwargs: Any) -> None:
         if self.isEnabledFor(logging.DEBUG):
             self._log_with_kv(logging.DEBUG, msg, args, **kwargs)
 
-    def info(self, msg: object, *args: object, **kwargs: Any) -> None:  # type: ignore[override]
+    def info(self, msg: object, *args: object, **kwargs: Any) -> None:
         if self.isEnabledFor(logging.INFO):
             self._log_with_kv(logging.INFO, msg, args, **kwargs)
 
-    def warning(self, msg: object, *args: object, **kwargs: Any) -> None:  # type: ignore[override]
+    def warning(self, msg: object, *args: object, **kwargs: Any) -> None:
         if self.isEnabledFor(logging.WARNING):
             self._log_with_kv(logging.WARNING, msg, args, **kwargs)
 
-    def error(self, msg: object, *args: object, **kwargs: Any) -> None:  # type: ignore[override]
+    def error(self, msg: object, *args: object, **kwargs: Any) -> None:
         if self.isEnabledFor(logging.ERROR):
             self._log_with_kv(logging.ERROR, msg, args, **kwargs)
 
-    def critical(self, msg: object, *args: object, **kwargs: Any) -> None:  # type: ignore[override]
+    def critical(self, msg: object, *args: object, **kwargs: Any) -> None:
         if self.isEnabledFor(logging.CRITICAL):
             self._log_with_kv(logging.CRITICAL, msg, args, **kwargs)
 
-    def exception(self, msg: object, *args: object, **kwargs: Any) -> None:  # type: ignore[override]
+    def exception(self, msg: object, *args: object, **kwargs: Any) -> None:
         kwargs.setdefault("exc_info", True)
         if self.isEnabledFor(logging.ERROR):
             self._log_with_kv(logging.ERROR, msg, args, **kwargs)
 
-    def log(self, level: int, msg: object, *args: object, **kwargs: Any) -> None:  # type: ignore[override]
-        if not isinstance(level, int):
+    def log(self, level: int, msg: object, *args: object, **kwargs: Any) -> None:
+        if not isinstance(level, int):  # pyright: ignore[reportUnnecessaryIsInstance]
             raise TypeError("level must be an int")
         if self.isEnabledFor(level):
             self._log_with_kv(level, msg, args, **kwargs)
@@ -313,7 +311,7 @@ class _ThirdPartySelectorFilter(logging.Filter):
         self.app_logger_prefix = app_logger_prefix
         self.spotlight_prefixes = spotlight_prefixes
 
-    def filter(self, record: logging.LogRecord) -> bool:  # noqa: A003
+    def filter(self, record: logging.LogRecord) -> bool:
         name = record.name
         if name == self.app_logger_prefix or name.startswith(self.app_logger_prefix + "."):
             return True
@@ -466,9 +464,7 @@ def configure_logging(
     handler.setLevel(logging.NOTSET)
     handler.setFormatter(formatter)
     handler.addFilter(
-        _ThirdPartySelectorFilter(
-            app_logger_prefix=app_logger_prefix, spotlight_prefixes=tuple(spotlight)
-        )
+        _ThirdPartySelectorFilter(app_logger_prefix=app_logger_prefix, spotlight_prefixes=tuple(spotlight))
     )
 
     # Configure root.
@@ -532,11 +528,7 @@ def iter_recent_log_lines(log_file: Path, since: timedelta) -> list[str]:
     cutoff = _now_utc() - since
 
     candidates = sorted(
-        [
-            p
-            for p in log_file.parent.glob(log_file.name + "*")
-            if p.is_file() and not p.name.endswith(".gz")
-        ],
+        [p for p in log_file.parent.glob(log_file.name + "*") if p.is_file() and not p.name.endswith(".gz")],
         key=lambda p: p.stat().st_mtime,
     )
 
@@ -556,6 +548,46 @@ def iter_recent_log_lines(log_file: Path, since: timedelta) -> list[str]:
     return lines
 
 
+# Initial backward-probe size for locating the start of the --since window in a
+# large file. A typical multi-minute window fits in one or two probes; the probe
+# doubles when the window is larger, so worst case is still O(window), not O(file).
+_WINDOW_PROBE_BYTES = 262144  # 256 KiB
+
+
+def _window_start_offset(path: Path, cutoff: datetime) -> int:
+    """Return a byte offset at or before the first line newer than `cutoff`.
+
+    A log file is appended in timestamp order, so the window's start can be found
+    by probing backward from EOF in exponentially growing chunks instead of
+    scanning from byte 0: once a probe's earliest timestamped line is already
+    older than the cutoff, the window begins within that probe and everything
+    before it is skippable. Returns 0 when the window spans the whole file (or the
+    file is smaller than a single probe), which reproduces a full forward scan.
+    """
+    try:
+        size = path.stat().st_size
+    except OSError:
+        return 0
+    if size <= _WINDOW_PROBE_BYTES:
+        return 0
+
+    probe = _WINDOW_PROBE_BYTES
+    with path.open("rb") as fb:
+        while probe < size:
+            start = size - probe
+            fb.seek(start)
+            fb.readline()  # discard the partial line spanning the probe boundary
+            first_ts: datetime | None = None
+            for raw in fb:
+                first_ts = parse_log_timestamp(raw.decode("utf-8", errors="replace"))
+                if first_ts is not None:
+                    break
+            if first_ts is not None and first_ts < cutoff:
+                return start
+            probe *= 2
+    return 0
+
+
 def iter_recent_log_lines_merged(files: Iterable[Path], since: timedelta) -> Iterator[str]:
     """Yield lines newer than now-`since` merged across multiple files by timestamp.
 
@@ -575,12 +607,17 @@ def iter_recent_log_lines_merged(files: Iterable[Path], since: timedelta) -> Ite
 
     def _file_stream(path: Path) -> Iterator[tuple[datetime, str]]:
         try:
-            f = path.open("r", encoding="utf-8", errors="replace")
+            fb = path.open("rb")
         except FileNotFoundError:
             return
         try:
+            offset = _window_start_offset(path, cutoff)
+            if offset:
+                fb.seek(offset)
+                fb.readline()  # discard the partial line at the seek boundary
             last_ts: datetime | None = None
-            for line in f:
+            for raw in fb:
+                line = raw.decode("utf-8", errors="replace")
                 ts = parse_log_timestamp(line)
                 if ts is None:
                     if last_ts is None or last_ts < cutoff:
@@ -592,12 +629,12 @@ def iter_recent_log_lines_merged(files: Iterable[Path], since: timedelta) -> Ite
                     continue
                 yield (ts, line)
         finally:
-            f.close()
+            fb.close()
 
     eligible: list[Path] = []
     for path in files:
         try:
-            mtime = datetime.fromtimestamp(path.stat().st_mtime, tz=timezone.utc)
+            mtime = datetime.fromtimestamp(path.stat().st_mtime, tz=UTC)
         except OSError:
             continue
         if mtime < cutoff:

{instruktai_python_logger-0.4.5 → instruktai_python_logger-0.5.1}/instruktai_python_logger.egg-info/PKG-INFO

@@ -1,12 +1,9 @@
 Metadata-Version: 2.4
 Name: instruktai-python-logger
-Version: 0.4.5
+Version: 0.5.1
 Summary: Centralized logging utilities for Python services.
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
-Provides-Extra: dev
-Requires-Dist: pytest>=8; extra == "dev"
-Requires-Dist: ruff>=0.8; extra == "dev"
 
 # InstruktAI Python Logger
 
@@ -22,7 +19,7 @@ Publishing notes live in `docs/publishing.md`.
 From PyPI (recommended):
 
 ```bash
-pip install instrukt-ai-logger
+pip install instruktai-python-logger
 ```
 
 From GitHub:

{instruktai_python_logger-0.4.5 → instruktai_python_logger-0.5.1}/instruktai_python_logger.egg-info/SOURCES.txt

@@ -9,9 +9,9 @@ instruktai_python_logger.egg-info/PKG-INFO
 instruktai_python_logger.egg-info/SOURCES.txt
 instruktai_python_logger.egg-info/dependency_links.txt
 instruktai_python_logger.egg-info/entry_points.txt
-instruktai_python_logger.egg-info/requires.txt
 instruktai_python_logger.egg-info/top_level.txt
 tests/test_cli_follow.py
 tests/test_configure_logging.py
+tests/test_install.py
 tests/test_log_aggregation.py
 tests/test_trace_logging.py