instruktai-python-logger 0.6.5__tar.gz → 0.6.7__tar.gz

{instruktai_python_logger-0.6.5 → instruktai_python_logger-0.6.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: instruktai-python-logger
-Version: 0.6.5
+Version: 0.6.7
 Summary: Centralized logging utilities for Python services.
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown

{instruktai_python_logger-0.6.5 → instruktai_python_logger-0.6.7}/instrukt_ai_logging/__init__.py

@@ -3,6 +3,19 @@
 See `README.md` for usage and `docs/design.md` for design intent.
 """
 
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _pkg_version
+
+from instrukt_ai_logging.logging import (
+    TRACE,
+    InstruktAILogger,
+    InstruktAILoggerProtocol,
+    configure_logging,
+    get_logger,
+    resolve_log_file,
+    resolve_log_files,
+)
+
 __all__ = [
     "TRACE",
     "InstruktAILogger",
@@ -14,21 +27,9 @@ __all__ = [
     "resolve_log_files",
 ]
 
-try:
-    from importlib.metadata import packages_distributions
-    from importlib.metadata import version as _pkg_version
+_DISTRIBUTION_NAME = "instruktai-python-logger"
 
-    _dists = packages_distributions().get(__name__, [])
-    __version__ = _pkg_version(_dists[0]) if _dists else "0.0.0"
-except Exception:  # pragma: no cover
+try:
+    __version__ = _pkg_version(_DISTRIBUTION_NAME)
+except PackageNotFoundError:
     __version__ = "0.0.0"
-
-from instrukt_ai_logging.logging import (
-    TRACE,
-    InstruktAILogger,
-    InstruktAILoggerProtocol,
-    configure_logging,
-    get_logger,
-    resolve_log_file,
-    resolve_log_files,
-)

{instruktai_python_logger-0.6.5 → instruktai_python_logger-0.6.7}/instrukt_ai_logging/cli.py

@@ -7,10 +7,12 @@ import sys
 import threading
 import time
 from collections.abc import Iterator
+from datetime import datetime
 from pathlib import Path
 
 from instrukt_ai_logging.logging import (
     iter_recent_log_lines_merged,
+    newest_log_timestamp,
     parse_since,
     resolve_log_files,
 )
@@ -98,6 +100,18 @@ def iter_follow_lines(
                 pass
 
 
+_TIMESTAMP_STRFTIME_FORMAT = "%Y-%m-%dT%H:%M:%S"
+_TIMESTAMP_MS_SUFFIX_TEMPLATE = ".{ms:03d}Z"
+_NO_TIMESTAMPED_ENTRY_LABEL = "no timestamped entry"
+_EMPTY_RESULT_NOTE_TEMPLATE = "No lines matched. Resolved log root: {log_root}. Newest entry in that root: {newest}."
+
+
+def _format_timestamp(ts: datetime) -> str:
+    """Format a timestamp the same way log lines carry theirs (ms precision, `Z`)."""
+    ms = int(ts.microsecond / 1000)
+    return ts.strftime(_TIMESTAMP_STRFTIME_FORMAT) + _TIMESTAMP_MS_SUFFIX_TEMPLATE.format(ms=ms)
+
+
 def _parse_stems(value: str) -> list[str]:
     return [item.strip() for item in value.split(",") if item.strip()]
 
@@ -236,11 +250,21 @@ def main() -> None:
             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}'")
 
+    wrote_a_line = False
     for line in iter_recent_log_lines_merged(files, since):
         if _line_passes(line, keep=pattern, drop=exclude_pattern):
             sys.stdout.write(line)
+            wrote_a_line = True
 
     if not args.follow:
+        if not wrote_a_line:
+            log_root = files[0].parent
+            newest = newest_log_timestamp(files)
+            newest_desc = _format_timestamp(newest) if newest is not None else _NO_TIMESTAMPED_ENTRY_LABEL
+            print(
+                _EMPTY_RESULT_NOTE_TEMPLATE.format(log_root=log_root, newest=newest_desc),
+                file=sys.stderr,
+            )
         return
 
     sys.stdout.flush()

{instruktai_python_logger-0.6.5 → instruktai_python_logger-0.6.7}/instrukt_ai_logging/install.py

@@ -17,6 +17,17 @@ from pathlib import Path
 _NEWSYSLOG_BIN = "/usr/sbin/newsyslog"
 _LAUNCHD_LABEL = "ai.instrukt.log-rotate"
 _SYSTEMD_UNIT_NAME = "instrukt-ai-logrotate"
+_ARCHIVE_DEPTH = 30
+_NEWSYSLOG_CONF_TEMPLATE = "{log_root}/*/*.log  640  {archive_depth}  50000  *  ZG\n"
+_LOGROTATE_CONF_TEMPLATE = """{log_root}/*/*.log {{
+    size 50M
+    rotate {archive_depth}
+    compress
+    delaycompress
+    missingok
+    notifempty
+}}
+"""
 
 
 def _state_home_root() -> Path:
@@ -55,8 +66,8 @@ def _systemd_timer_path() -> Path:
 
 
 def _newsyslog_conf(log_root: Path) -> str:
-    """One glob line: 5 gzipped archives at 50 MB, evaluated at rotation time (G flag)."""
-    return f"{log_root}/*/*.log  640  5  50000  *  ZG\n"
+    """One glob line for gzip-compressed archive retention."""
+    return _NEWSYSLOG_CONF_TEMPLATE.format(log_root=log_root, archive_depth=_ARCHIVE_DEPTH)
 
 
 def _launchd_plist(conf_path: Path) -> str:
@@ -87,15 +98,7 @@ def _launchd_plist(conf_path: Path) -> str:
 
 def _logrotate_conf(log_root: Path) -> str:
     """Default move+create rotation; WatchedFileHandler reopens on inode change."""
-    return f"""{log_root}/*/*.log {{
-    size 50M
-    rotate 5
-    compress
-    delaycompress
-    missingok
-    notifempty
-}}
-"""
+    return _LOGROTATE_CONF_TEMPLATE.format(log_root=log_root, archive_depth=_ARCHIVE_DEPTH)
 
 
 def _systemd_service(conf_path: Path, state_file: Path) -> str:

{instruktai_python_logger-0.6.5 → instruktai_python_logger-0.6.7}/instrukt_ai_logging/logging.py

@@ -10,7 +10,7 @@ from dataclasses import dataclass
 from datetime import UTC, datetime, timedelta
 from logging.handlers import WatchedFileHandler
 from pathlib import Path
-from typing import Any, Protocol, cast, runtime_checkable
+from typing import Any, Literal, Protocol, cast, runtime_checkable
 
 # Standard logging levels are: NOTSET=0, DEBUG=10, INFO=20, WARNING=30, ERROR=40, CRITICAL=50
 TRACE: int = 5
@@ -587,6 +587,94 @@ def _window_start_offset(path: Path, cutoff: datetime) -> int:
     return 0
 
 
+_GZIP_SUFFIX = ".gz"
+_BINARY_READ_MODE: Literal["rb"] = "rb"
+_TEXT_DECODE_ENCODING = "utf-8"
+_TEXT_DECODE_ERRORS = "replace"
+
+
+def _tail_timestamp(path: Path) -> datetime | None:
+    """Return the newest parsable log timestamp near the tail of `path`, or `None`.
+
+    A log file is appended in timestamp order, so its newest entry is always at
+    the tail: probe backward in exponentially growing chunks (the same
+    `_WINDOW_PROBE_BYTES` doubling idiom `_window_start_offset` uses) until the
+    probed span holds at least one parsable timestamp, then return the last one
+    seen while scanning that span forward to EOF — ascending order makes that the
+    maximum. Falls back to a full scan only when no probe finds a timestamp at
+    all. Gzip archives have no seek and are streamed from the start; the caller's
+    mtime bound already governs whether this is called on one.
+
+    Only a vanished file (`FileNotFoundError`, the same race every sibling probe
+    in this module already tolerates) is treated as absence. A file that exists
+    but cannot be read or decompressed — permission denied, a truncated or
+    corrupt archive — propagates its exception rather than being reported as
+    holding no timestamp.
+    """
+    if path.name.endswith(_GZIP_SUFFIX):
+        newest: datetime | None = None
+        try:
+            with gzip.open(path, _BINARY_READ_MODE) as fb:
+                for raw in fb:
+                    ts = parse_log_timestamp(raw.decode(_TEXT_DECODE_ENCODING, errors=_TEXT_DECODE_ERRORS))
+                    if ts is not None:
+                        newest = ts
+        except FileNotFoundError:
+            return None
+        return newest
+
+    try:
+        size = path.stat().st_size
+    except FileNotFoundError:
+        return None
+
+    probe = _WINDOW_PROBE_BYTES
+    with path.open(_BINARY_READ_MODE) as fb:
+        while True:
+            start = max(0, size - probe)
+            fb.seek(start)
+            if start:
+                fb.readline()  # discard the partial line spanning the probe boundary
+            newest = None
+            for raw in fb:
+                ts = parse_log_timestamp(raw.decode(_TEXT_DECODE_ENCODING, errors=_TEXT_DECODE_ERRORS))
+                if ts is not None:
+                    newest = ts
+            if newest is not None or start == 0:
+                return newest
+            probe *= 2
+
+
+def newest_log_timestamp(files: Iterable[Path]) -> datetime | None:
+    """Return the newest parsable log timestamp across `files`, or `None`.
+
+    Examines files in descending mtime order. A file's entries never postdate
+    its own mtime — the bound `iter_recent_log_lines_merged` already relies on
+    to skip whole files — so once a remaining candidate's mtime can no longer
+    beat the best timestamp found so far, no later candidate can either and the
+    scan stops. A single file's mtime is not enough on its own to answer this:
+    the root holds independent per-stem streams and their rotations, so the
+    newest entry can live in a file that was not the most recently touched.
+    """
+    candidates: list[tuple[float, Path]] = []
+    for path in files:
+        try:
+            mtime = path.stat().st_mtime
+        except FileNotFoundError:
+            continue
+        candidates.append((mtime, path))
+    candidates.sort(key=lambda item: item[0], reverse=True)
+
+    best: datetime | None = None
+    for mtime, path in candidates:
+        if best is not None and datetime.fromtimestamp(mtime, tz=UTC) <= best:
+            break
+        ts = _tail_timestamp(path)
+        if ts is not None and (best is None or ts > best):
+            best = ts
+    return best
+
+
 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.
 

{instruktai_python_logger-0.6.5 → instruktai_python_logger-0.6.7}/instruktai_python_logger.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: instruktai-python-logger
-Version: 0.6.5
+Version: 0.6.7
 Summary: Centralized logging utilities for Python services.
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown

{instruktai_python_logger-0.6.5 → instruktai_python_logger-0.6.7}/pyproject.toml

@@ -4,14 +4,14 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "instruktai-python-logger"
-version = "0.6.5"
+version = "0.6.7"
 description = "Centralized logging utilities for Python services."
 readme = "README.md"
 requires-python = ">=3.11"
 dependencies = []
 
 [dependency-groups]
-dev = ["pytest>=8", "pytest-timeout>=2.2.0", "ruff>=0.8", "pyright>=1.1", "mypy>=1.10"]
+dev = ["pytest>=8", "pytest-timeout>=2.2.0", "ruff>=0.8", "pyright>=1.1", "mypy>=1.10", "syrupy>=4"]
 
 [project.scripts]
 instrukt-ai-logs = "instrukt_ai_logging.cli:main"

{instruktai_python_logger-0.6.5 → instruktai_python_logger-0.6.7}/tests/test_configure_logging.py

@@ -7,9 +7,8 @@ from tempfile import TemporaryDirectory
 import pytest
 from instrukt_ai_logging import InstruktAILogger, configure_logging, get_logger
 
-# Log markers shared by each test and its assertions — named constants per
-# software-development/procedure/snapshot-testing (no bare literals in content
-# assertions). The logfmt field fragments are derived from the markers so the
+# Log markers shared by each test and its assertions — named
+# constants. The logfmt field fragments are derived from the markers so the
 # expected output stays in sync with what is logged.
 _LOGGER_OURS = "teleclaude.core"
 _LOGGER_HTTPCORE = "httpcore.http11"

{instruktai_python_logger-0.6.5 → instruktai_python_logger-0.6.7}/tests/test_install.py

@@ -8,12 +8,9 @@ from pathlib import Path
 import pytest
 from instrukt_ai_logging import install
 
-# Protocol-significant tokens for the rotation configs — named constants per
-# software-development/procedure/snapshot-testing (no bare literals in content
-# assertions). These are newsyslog/logrotate/launchd/systemd field identities,
-# not prose.
+# Protocol-significant tokens the rotation-config assertions check for, named as
+# constants. These are newsyslog/logrotate/launchd/systemd field identities, not prose.
 _NEWSYSLOG_MODE = "640"
-_NEWSYSLOG_COUNT = "5"
 _NEWSYSLOG_SIZE_KB = "50000"
 _NEWSYSLOG_WHEN = "*"
 _NEWSYSLOG_COMPRESS_GLOB_FLAGS = "ZG"  # gzip-compress archives; glob-expand at rotation time
@@ -22,7 +19,6 @@ _PLIST_PROGRAM = "/usr/sbin/newsyslog"
 _PLIST_NO_ROOT_FLAG = "<string>-r</string>"  # newsyslog otherwise refuses to run as a non-root user
 _PLIST_START_INTERVAL = "1800"
 _LOGROTATE_SIZE = "size 50M"
-_LOGROTATE_ROTATE = "rotate 5"
 _LOGROTATE_COMPRESS = "compress"
 _LOGROTATE_DELAYCOMPRESS = "delaycompress"
 _LOGROTATE_MISSINGOK = "missingok"
@@ -82,10 +78,9 @@ def test_ensure_rotation_darwin_writes_newsyslog_conf_and_plist(
 
     assert problems == []
     conf_content = install._newsyslog_conf_path().read_text(encoding="utf-8")
-    path, mode, count, size_kb, when, flags = conf_content.split()
+    path, mode, _count, size_kb, when, flags = conf_content.split()
     assert path == f"{rotation_env / 'instrukt-ai'}/*/*.log"
     assert mode == _NEWSYSLOG_MODE
-    assert count == _NEWSYSLOG_COUNT
     assert size_kb == _NEWSYSLOG_SIZE_KB
     assert when == _NEWSYSLOG_WHEN
     assert flags == _NEWSYSLOG_COMPRESS_GLOB_FLAGS
@@ -115,7 +110,6 @@ def test_ensure_rotation_linux_writes_logrotate_conf_and_systemd_units(
     assert f"{rotation_env / 'instrukt-ai'}/*/*.log" in logrotate_content
     for directive in (
         _LOGROTATE_SIZE,
-        _LOGROTATE_ROTATE,
         _LOGROTATE_COMPRESS,
         _LOGROTATE_DELAYCOMPRESS,
         _LOGROTATE_MISSINGOK,

{instruktai_python_logger-0.6.5 → instruktai_python_logger-0.6.7}/tests/test_log_aggregation.py

@@ -19,9 +19,8 @@ def _write(path: Path, content: str) -> None:
     path.write_text(content, encoding="utf-8")
 
 
-# Log markers shared by each fixture and its assertions — named constants per
-# software-development/procedure/snapshot-testing (no bare literals in content
-# assertions).
+# Log markers shared by each fixture and its assertions — named
+# constants.
 _MSG_FRESH = "fresh"
 _MSG_BOOM = "boom"
 _MSG_AFTER = "after"

{instruktai_python_logger-0.6.5 → instruktai_python_logger-0.6.7}/tests/test_trace_logging.py

@@ -7,9 +7,8 @@ from instrukt_ai_logging.logging import (
     get_logger,
 )
 
-# Log markers shared by each test and its assertions — named constants per
-# software-development/procedure/snapshot-testing (no bare literals in content
-# assertions). The logfmt field fragments are derived from the markers so the
+# Log markers shared by each test and its assertions — named
+# constants. The logfmt field fragments are derived from the markers so the
 # expected output stays in sync with what is logged.
 _TRACE_MSG = "This is a trace message"
 _DEBUG_MSG = "This is a debug message"