instruktai-python-logger 0.5.0__tar.gz → 0.6.0__tar.gz

{instruktai_python_logger-0.5.0 → instruktai_python_logger-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: instruktai-python-logger
-Version: 0.5.0
+Version: 0.6.0
 Summary: Centralized logging utilities for Python services.
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
@@ -58,8 +58,8 @@ configure_logging("teleclaude", source="cron")        # → cron.log
 ```
 
 The `.log` extension is always appended; pass the bare stem. Files all live
-under `/var/log/instrukt-ai/{app}/`. The CLI merges them transparently
-(see below).
+under `$XDG_STATE_HOME/instrukt-ai/{app}/` (fallback `~/.local/state`). The CLI
+merges them transparently (see below).
 
 ## Environment variables (contract)
 
@@ -70,17 +70,32 @@ Per-app prefix model (example uses `TELECLAUDE_`):
 - `TELECLAUDE_THIRD_PARTY_LOGGERS` (comma-separated logger prefixes to spotlight, e.g. `httpcore,telegram`)
 - `TELECLAUDE_MUTED_LOGGERS` (comma-separated logger prefixes to force to WARNING+, e.g. `teleclaude.cli.tui`)
 
-Global:
-
-- `INSTRUKT_AI_LOG_ROOT` (optional log root override)
+These four per-app variables are the entire contract. There is no log-root
+override variable — the location is a fixed rule (see below).
 
 ## Log location (contract)
 
-Default target:
+Every app's logs live at the same predictable, prose-citable location on both
+macOS and Linux:
+
+- `$XDG_STATE_HOME/instrukt-ai/{app}/{app}.log` (fallback `~/.local/state`,
+  per the XDG Base Directory spec)
+
+This path is always user-writable — no installer step, no sudo, no elevated
+permissions. `configure_logging(...)` raises immediately if the log file
+cannot be opened; logging is an essential subsystem and a process that cannot
+write its logs must not start blind.
 
-- `/var/log/instrukt-ai/{app}/{app}.log`
+## Rotation
 
-The installer for each service is expected to create the directory and set write permissions for the daemon user. If the default location is not writable, the implementation will fall back to a user-writable directory and/or require `INSTRUKT_AI_LOG_ROOT`.
+Rotation is transparent and runs entirely in user space:
+`configure_logging(...)` idempotently ensures a per-user rotation conf plus a
+per-user scheduler (a launchd LaunchAgent on macOS running `newsyslog`, a
+systemd user timer on Linux running `logrotate`) on every process start. No
+`/etc` configuration, no sudo, and no system rotation daemon ever touches
+these files, so rotated/recreated logs always stay owned by the producing
+user. Run `instrukt-ai-log-setup` to check rotation-asset status manually;
+normal operation never requires it.
 
 ## CLI
 

{instruktai_python_logger-0.5.0 → instruktai_python_logger-0.6.0}/README.md

@@ -51,8 +51,8 @@ configure_logging("teleclaude", source="cron")        # → cron.log
 ```
 
 The `.log` extension is always appended; pass the bare stem. Files all live
-under `/var/log/instrukt-ai/{app}/`. The CLI merges them transparently
-(see below).
+under `$XDG_STATE_HOME/instrukt-ai/{app}/` (fallback `~/.local/state`). The CLI
+merges them transparently (see below).
 
 ## Environment variables (contract)
 
@@ -63,17 +63,32 @@ Per-app prefix model (example uses `TELECLAUDE_`):
 - `TELECLAUDE_THIRD_PARTY_LOGGERS` (comma-separated logger prefixes to spotlight, e.g. `httpcore,telegram`)
 - `TELECLAUDE_MUTED_LOGGERS` (comma-separated logger prefixes to force to WARNING+, e.g. `teleclaude.cli.tui`)
 
-Global:
-
-- `INSTRUKT_AI_LOG_ROOT` (optional log root override)
+These four per-app variables are the entire contract. There is no log-root
+override variable — the location is a fixed rule (see below).
 
 ## Log location (contract)
 
-Default target:
+Every app's logs live at the same predictable, prose-citable location on both
+macOS and Linux:
+
+- `$XDG_STATE_HOME/instrukt-ai/{app}/{app}.log` (fallback `~/.local/state`,
+  per the XDG Base Directory spec)
+
+This path is always user-writable — no installer step, no sudo, no elevated
+permissions. `configure_logging(...)` raises immediately if the log file
+cannot be opened; logging is an essential subsystem and a process that cannot
+write its logs must not start blind.
 
-- `/var/log/instrukt-ai/{app}/{app}.log`
+## Rotation
 
-The installer for each service is expected to create the directory and set write permissions for the daemon user. If the default location is not writable, the implementation will fall back to a user-writable directory and/or require `INSTRUKT_AI_LOG_ROOT`.
+Rotation is transparent and runs entirely in user space:
+`configure_logging(...)` idempotently ensures a per-user rotation conf plus a
+per-user scheduler (a launchd LaunchAgent on macOS running `newsyslog`, a
+systemd user timer on Linux running `logrotate`) on every process start. No
+`/etc` configuration, no sudo, and no system rotation daemon ever touches
+these files, so rotated/recreated logs always stay owned by the producing
+user. Run `instrukt-ai-log-setup` to check rotation-asset status manually;
+normal operation never requires it.
 
 ## CLI
 

{instruktai_python_logger-0.5.0 → instruktai_python_logger-0.6.0}/instrukt_ai_logging/cli.py

@@ -192,7 +192,9 @@ def main() -> None:
         action="version",
         version=f"%(prog)s {__version__}",
     )
-    parser.add_argument("app", help="App/service name (folder under /var/log/instrukt-ai/)")
+    parser.add_argument(
+        "app", help="App/service name (folder under $XDG_STATE_HOME/instrukt-ai/, fallback ~/.local/state)"
+    )
     parser.add_argument("--since", default="10m", help="Time window (e.g. 10m, 2h, 1d). Default: 10m")
     parser.add_argument(
         "-f",

instruktai_python_logger-0.6.0/instrukt_ai_logging/install.py

@@ -0,0 +1,232 @@
+"""Ensure user-space log rotation assets for InstruktAI logs.
+
+Rotation runs entirely as the producing user: a per-user rotation conf plus a
+per-user scheduler (launchd LaunchAgent on macOS, systemd user timer on
+Linux). No `/etc` configuration, no sudo, no system rotation daemon ever
+touches these files, so root-owned recreated logs are structurally
+unexpressible.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+_NEWSYSLOG_BIN = "/usr/sbin/newsyslog"
+_LAUNCHD_LABEL = "ai.instrukt.log-rotate"
+_SYSTEMD_UNIT_NAME = "instrukt-ai-logrotate"
+
+
+def _state_home_root() -> Path:
+    """Resolve `$XDG_STATE_HOME/instrukt-ai` (fallback `~/.local/state`)."""
+    xdg_state_home = os.getenv("XDG_STATE_HOME")
+    state_home = Path(xdg_state_home).expanduser() if xdg_state_home else Path("~/.local/state").expanduser()
+    return state_home / "instrukt-ai"
+
+
+def _config_dir() -> Path:
+    return Path.home() / ".config" / "instrukt-ai"
+
+
+def _newsyslog_conf_path() -> Path:
+    return _config_dir() / "newsyslog.conf"
+
+
+def _launchd_plist_path() -> Path:
+    return Path.home() / "Library" / "LaunchAgents" / f"{_LAUNCHD_LABEL}.plist"
+
+
+def _logrotate_conf_path() -> Path:
+    return _config_dir() / "logrotate.conf"
+
+
+def _systemd_user_dir() -> Path:
+    return Path.home() / ".config" / "systemd" / "user"
+
+
+def _systemd_service_path() -> Path:
+    return _systemd_user_dir() / f"{_SYSTEMD_UNIT_NAME}.service"
+
+
+def _systemd_timer_path() -> Path:
+    return _systemd_user_dir() / f"{_SYSTEMD_UNIT_NAME}.timer"
+
+
+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"
+
+
+def _launchd_plist(conf_path: Path) -> str:
+    # newsyslog refuses to run at all unless invoked as root or with -r; our
+    # conf lines carry no pid/signal field, so -r's "won't HUP syslogd" caveat
+    # doesn't apply here.
+    return f"""<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>{_LAUNCHD_LABEL}</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>{_NEWSYSLOG_BIN}</string>
+        <string>-r</string>
+        <string>-f</string>
+        <string>{conf_path}</string>
+    </array>
+    <key>StartInterval</key>
+    <integer>1800</integer>
+    <key>RunAtLoad</key>
+    <true/>
+</dict>
+</plist>
+"""
+
+
+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
+}}
+"""
+
+
+def _systemd_service(conf_path: Path, state_file: Path) -> str:
+    return f"""[Unit]
+Description=InstruktAI log rotation
+
+[Service]
+Type=oneshot
+ExecStart=logrotate --state {state_file} {conf_path}
+"""
+
+
+def _systemd_timer() -> str:
+    return """[Unit]
+Description=InstruktAI log rotation timer
+
+[Timer]
+OnCalendar=*:0/30
+Persistent=true
+
+[Install]
+WantedBy=timers.target
+"""
+
+
+def _write_if_changed(path: Path, content: str) -> None:
+    if path.exists() and path.read_text(encoding="utf-8") == content:
+        return
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(content, encoding="utf-8")
+
+
+_SCHEDULER_COMMAND_TIMEOUT_S = 10.0
+
+
+def _run_scheduler_command(args: list[str]) -> subprocess.CompletedProcess[str]:
+    # No Python API wraps launchd's per-user service bus or the systemd user
+    # D-Bus/session manager; shell out to launchctl/systemctl. Routed through
+    # this wrapper (rather than calling subprocess.run directly) so tests can
+    # fake just this boundary without patching the shared subprocess module.
+    # A bounded timeout and closed stdin keep an unreachable service bus (no
+    # GUI/user session, e.g. a headless CI runner) from hanging the caller
+    # forever instead of failing fast.
+    return subprocess.run(
+        args,
+        capture_output=True,
+        text=True,
+        stdin=subprocess.DEVNULL,
+        timeout=_SCHEDULER_COMMAND_TIMEOUT_S,
+    )
+
+
+def _ensure_launchd_loaded(plist_path: Path) -> list[str]:
+    uid = os.getuid()
+    try:
+        result = _run_scheduler_command(["launchctl", "bootstrap", f"gui/{uid}", str(plist_path)])
+    except (OSError, subprocess.TimeoutExpired) as exc:
+        return [f"launchctl bootstrap failed to run: {exc}"]
+
+    if result.returncode != 0 and "already bootstrapped" not in result.stderr.lower():
+        return [f"launchctl bootstrap failed: {result.stderr.strip()}"]
+    return []
+
+
+def _ensure_systemd_loaded() -> list[str]:
+    try:
+        reload_result = _run_scheduler_command(["systemctl", "--user", "daemon-reload"])
+    except (OSError, subprocess.TimeoutExpired) as exc:
+        return [f"systemctl daemon-reload failed to run: {exc}"]
+
+    if reload_result.returncode != 0:
+        return [f"systemctl daemon-reload failed: {reload_result.stderr.strip()}"]
+
+    try:
+        enable_result = _run_scheduler_command(
+            ["systemctl", "--user", "enable", "--now", f"{_SYSTEMD_UNIT_NAME}.timer"]
+        )
+    except (OSError, subprocess.TimeoutExpired) as exc:
+        return [f"systemctl enable failed to run: {exc}"]
+
+    if enable_result.returncode != 0:
+        return [f"systemctl enable failed: {enable_result.stderr.strip()}"]
+    return []
+
+
+def ensure_rotation() -> list[str]:
+    """Idempotently ensure user-space rotation assets exist and are scheduled.
+
+    Never raises. Returns human-readable problem strings for anything that
+    could not be resolved; an empty list means rotation is healthy.
+    """
+    log_root = _state_home_root()
+
+    if sys.platform == "darwin":
+        conf_path = _newsyslog_conf_path()
+        plist_path = _launchd_plist_path()
+        try:
+            _write_if_changed(conf_path, _newsyslog_conf(log_root))
+            _write_if_changed(plist_path, _launchd_plist(conf_path))
+        except OSError as exc:
+            return [f"could not write rotation assets: {exc}"]
+        return _ensure_launchd_loaded(plist_path)
+
+    conf_path = _logrotate_conf_path()
+    service_path = _systemd_service_path()
+    timer_path = _systemd_timer_path()
+    state_file = log_root / "logrotate.state"
+    try:
+        _write_if_changed(conf_path, _logrotate_conf(log_root))
+        _write_if_changed(service_path, _systemd_service(conf_path, state_file))
+        _write_if_changed(timer_path, _systemd_timer())
+    except OSError as exc:
+        return [f"could not write rotation assets: {exc}"]
+    return _ensure_systemd_loaded()
+
+
+def main() -> None:
+    log_root = _state_home_root()
+    sys.stdout.write(f"log root: {log_root}\n")
+    sys.stdout.write(
+        f"rotation conf: {_newsyslog_conf_path() if sys.platform == 'darwin' else _logrotate_conf_path()}\n"
+    )
+    sys.stdout.write(f"scheduler: {_launchd_plist_path() if sys.platform == 'darwin' else _systemd_timer_path()}\n")
+
+    problems = ensure_rotation()
+    if problems:
+        for problem in problems:
+            sys.stdout.write(f"problem: {problem}\n")
+        raise SystemExit(1)
+    sys.stdout.write("status: healthy\n")
+
+
+if __name__ == "__main__":
+    main()

{instruktai_python_logger-0.5.0 → instruktai_python_logger-0.6.0}/instrukt_ai_logging/logging.py

@@ -11,6 +11,8 @@ from logging.handlers import WatchedFileHandler
 from pathlib import Path
 from typing import Any, Protocol, cast, runtime_checkable
 
+from instrukt_ai_logging.install import ensure_rotation
+
 # Standard logging levels are: NOTSET=0, DEBUG=10, INFO=20, WARNING=30, ERROR=40, CRITICAL=50
 TRACE: int = 5
 logging.addLevelName(TRACE, "TRACE")
@@ -345,10 +347,9 @@ class LoggingContract:
 
 def _resolve_log_root(app_name: str) -> Path:
     fs_app_name = _normalize_app_name(app_name)
-    override = os.getenv("INSTRUKT_AI_LOG_ROOT")
-    if override:
-        return Path(override).expanduser() / fs_app_name
-    return Path("/var/log/instrukt-ai") / fs_app_name
+    xdg_state_home = os.getenv("XDG_STATE_HOME")
+    state_home = Path(xdg_state_home).expanduser() if xdg_state_home else Path("~/.local/state").expanduser()
+    return state_home / "instrukt-ai" / fs_app_name
 
 
 def _ensure_log_dir(log_dir: Path) -> None:
@@ -454,18 +455,19 @@ def configure_logging(
     root_level = third_party_level if not spotlight else logging.WARNING
 
     log_dir = _resolve_log_root(app_name)
-    _ensure_log_dir(log_dir)
-
     log_file = log_dir / log_filename
 
     formatter = LogfmtFormatter(max_message_chars=max_message_chars)
+    selector = _ThirdPartySelectorFilter(app_logger_prefix=app_logger_prefix, spotlight_prefixes=tuple(spotlight))
+
+    # Logging is an essential subsystem: an unwritable log dir/file raises here
+    # and the host process must not start blind. No degraded/fallback mode.
+    _ensure_log_dir(log_dir)
+    handler: logging.Handler = WatchedFileHandler(log_file, encoding="utf-8")
 
-    handler = WatchedFileHandler(log_file, encoding="utf-8")
     handler.setLevel(logging.NOTSET)
     handler.setFormatter(formatter)
-    handler.addFilter(
-        _ThirdPartySelectorFilter(app_logger_prefix=app_logger_prefix, spotlight_prefixes=tuple(spotlight))
-    )
+    handler.addFilter(selector)
 
     # Configure root.
     logging.root.handlers = [handler]
@@ -484,6 +486,11 @@ def configure_logging(
     for prefix in muted:
         logging.getLogger(prefix).setLevel(logging.WARNING)
 
+    # Rotation bootstrap is not logging: a failure here is surfaced as a
+    # warning, never fatal to an already-working log file.
+    for problem in ensure_rotation():
+        logging.getLogger(app_logger_prefix).warning("log rotation ensure problem: %s", problem)
+
     return log_file
 
 
@@ -548,6 +555,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.
 
@@ -567,12 +614,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:
@@ -584,7 +636,7 @@ 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:

{instruktai_python_logger-0.5.0 → instruktai_python_logger-0.6.0}/instruktai_python_logger.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: instruktai-python-logger
-Version: 0.5.0
+Version: 0.6.0
 Summary: Centralized logging utilities for Python services.
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
@@ -58,8 +58,8 @@ configure_logging("teleclaude", source="cron")        # → cron.log
 ```
 
 The `.log` extension is always appended; pass the bare stem. Files all live
-under `/var/log/instrukt-ai/{app}/`. The CLI merges them transparently
-(see below).
+under `$XDG_STATE_HOME/instrukt-ai/{app}/` (fallback `~/.local/state`). The CLI
+merges them transparently (see below).
 
 ## Environment variables (contract)
 
@@ -70,17 +70,32 @@ Per-app prefix model (example uses `TELECLAUDE_`):
 - `TELECLAUDE_THIRD_PARTY_LOGGERS` (comma-separated logger prefixes to spotlight, e.g. `httpcore,telegram`)
 - `TELECLAUDE_MUTED_LOGGERS` (comma-separated logger prefixes to force to WARNING+, e.g. `teleclaude.cli.tui`)
 
-Global:
-
-- `INSTRUKT_AI_LOG_ROOT` (optional log root override)
+These four per-app variables are the entire contract. There is no log-root
+override variable — the location is a fixed rule (see below).
 
 ## Log location (contract)
 
-Default target:
+Every app's logs live at the same predictable, prose-citable location on both
+macOS and Linux:
+
+- `$XDG_STATE_HOME/instrukt-ai/{app}/{app}.log` (fallback `~/.local/state`,
+  per the XDG Base Directory spec)
+
+This path is always user-writable — no installer step, no sudo, no elevated
+permissions. `configure_logging(...)` raises immediately if the log file
+cannot be opened; logging is an essential subsystem and a process that cannot
+write its logs must not start blind.
 
-- `/var/log/instrukt-ai/{app}/{app}.log`
+## Rotation
 
-The installer for each service is expected to create the directory and set write permissions for the daemon user. If the default location is not writable, the implementation will fall back to a user-writable directory and/or require `INSTRUKT_AI_LOG_ROOT`.
+Rotation is transparent and runs entirely in user space:
+`configure_logging(...)` idempotently ensures a per-user rotation conf plus a
+per-user scheduler (a launchd LaunchAgent on macOS running `newsyslog`, a
+systemd user timer on Linux running `logrotate`) on every process start. No
+`/etc` configuration, no sudo, and no system rotation daemon ever touches
+these files, so rotated/recreated logs always stay owned by the producing
+user. Run `instrukt-ai-log-setup` to check rotation-asset status manually;
+normal operation never requires it.
 
 ## CLI
 

{instruktai_python_logger-0.5.0 → instruktai_python_logger-0.6.0}/pyproject.toml

@@ -4,14 +4,14 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "instruktai-python-logger"
-version = "0.5.0"
+version = "0.6.0"
 description = "Centralized logging utilities for Python services."
 readme = "README.md"
 requires-python = ">=3.11"
 dependencies = []
 
 [dependency-groups]
-dev = ["pytest>=8", "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"]
 
 [project.scripts]
 instrukt-ai-logs = "instrukt_ai_logging.cli:main"
@@ -25,8 +25,17 @@ include = ["instrukt_ai_logging*"]
 instrukt_ai_logging = ["py.typed"]
 
 [tool.pytest.ini_options]
-addopts = "-q"
+addopts = "--strict-config --strict-markers --tb=short -q"
 testpaths = ["tests"]
+timeout = 5
+timeout_method = "signal"
+session_timeout = 90
+markers = [
+    "functional: fast, hermetic, no I/O beyond tmp_path",
+    "integration: exercises multiple in-process components together, still hermetic",
+    "process: drives an external process, bounded and hermetic (tmp_path/monkeypatch-isolated)",
+    "spec: binds a feature-spec scenario",
+]
 
 [tool.ruff]
 line-length = 120