instruktai-python-logger 0.1.5__tar.gz → 0.4.0__tar.gz

instruktai_python_logger-0.4.0/PKG-INFO

@@ -0,0 +1,111 @@
+Metadata-Version: 2.4
+Name: instruktai-python-logger
+Version: 0.4.0
+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
+
+Centralized logging utilities for Python services.
+
+This repo provides a shared, consistent logging contract (env vars + output format + log location) intended to keep logs highly queryable (including by AIs that only read a tail window).
+
+Background and rationale live in `docs/design.md`.
+Publishing notes live in `docs/publishing.md`.
+
+## Install (editable, local workspace)
+
+From PyPI (recommended):
+
+```bash
+pip install instrukt-ai-logger
+```
+
+From GitHub:
+
+```bash
+pip install git+ssh://git@github.com/InstruktAI/python-logger.git
+```
+
+## API
+
+- Python entrypoint: `instrukt_ai_logging.configure_logging(...)`
+- Logger helper: `instrukt_ai_logging.get_logger(name)` (named `**kv` logging)
+- CLI entrypoint: `instrukt-ai-logs` (reads recent log lines)
+
+Example:
+
+```py
+import logging
+from instrukt_ai_logging import configure_logging
+
+configure_logging("teleclaude")
+logger = logging.getLogger("teleclaude.core")
+logger.info("job_started", job_id="abc123", user_id=123)
+```
+
+### Per-process log files (multi-producer apps)
+
+When several processes belong to the same app (a daemon plus a watcher plus a
+cron, for example), each one can own its own file under the same app directory
+by passing `source=`:
+
+```py
+configure_logging("teleclaude")                       # → teleclaude.log (default)
+configure_logging("teleclaude", source="docs-watch")  # → docs-watch.log
+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).
+
+## Environment variables (contract)
+
+Per-app prefix model (example uses `TELECLAUDE_`):
+
+- `TELECLAUDE_LOG_LEVEL`
+- `TELECLAUDE_THIRD_PARTY_LOG_LEVEL`
+- `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)
+
+## Log location (contract)
+
+Default target:
+
+- `/var/log/instrukt-ai/{app}/{app}.log`
+
+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`.
+
+## CLI
+
+```bash
+# Last 10 minutes (default), follows
+instrukt-ai-logs teleclaude -f
+
+# Last 2 hours
+instrukt-ai-logs teleclaude --since 2h
+
+# Filter with regex
+instrukt-ai-logs teleclaude --since 10m --grep 'logger=teleclaude'
+
+# Follow (tail -f style) after printing the --since window
+instrukt-ai-logs teleclaude --since 10m --follow
+
+# Restrict to specific source streams (per-process files)
+instrukt-ai-logs teleclaude --since 1h --logs=cron,docs-watch
+```
+
+Without `--logs`, every `*.log*` file in the app directory is merged by
+timestamp (rotation suffixes included). With `--logs=stem1,stem2`, only files
+whose stem matches an entry are read — exact stem match, so `--logs=cron`
+picks `cron.log`, `cron.log.0`, `cron.log.1` and never `cron-backup.log`.
+Follow mode reads each selected file with one polling thread per file.

instruktai_python_logger-0.4.0/README.md

@@ -0,0 +1,101 @@
+# InstruktAI Python Logger
+
+Centralized logging utilities for Python services.
+
+This repo provides a shared, consistent logging contract (env vars + output format + log location) intended to keep logs highly queryable (including by AIs that only read a tail window).
+
+Background and rationale live in `docs/design.md`.
+Publishing notes live in `docs/publishing.md`.
+
+## Install (editable, local workspace)
+
+From PyPI (recommended):
+
+```bash
+pip install instrukt-ai-logger
+```
+
+From GitHub:
+
+```bash
+pip install git+ssh://git@github.com/InstruktAI/python-logger.git
+```
+
+## API
+
+- Python entrypoint: `instrukt_ai_logging.configure_logging(...)`
+- Logger helper: `instrukt_ai_logging.get_logger(name)` (named `**kv` logging)
+- CLI entrypoint: `instrukt-ai-logs` (reads recent log lines)
+
+Example:
+
+```py
+import logging
+from instrukt_ai_logging import configure_logging
+
+configure_logging("teleclaude")
+logger = logging.getLogger("teleclaude.core")
+logger.info("job_started", job_id="abc123", user_id=123)
+```
+
+### Per-process log files (multi-producer apps)
+
+When several processes belong to the same app (a daemon plus a watcher plus a
+cron, for example), each one can own its own file under the same app directory
+by passing `source=`:
+
+```py
+configure_logging("teleclaude")                       # → teleclaude.log (default)
+configure_logging("teleclaude", source="docs-watch")  # → docs-watch.log
+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).
+
+## Environment variables (contract)
+
+Per-app prefix model (example uses `TELECLAUDE_`):
+
+- `TELECLAUDE_LOG_LEVEL`
+- `TELECLAUDE_THIRD_PARTY_LOG_LEVEL`
+- `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)
+
+## Log location (contract)
+
+Default target:
+
+- `/var/log/instrukt-ai/{app}/{app}.log`
+
+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`.
+
+## CLI
+
+```bash
+# Last 10 minutes (default), follows
+instrukt-ai-logs teleclaude -f
+
+# Last 2 hours
+instrukt-ai-logs teleclaude --since 2h
+
+# Filter with regex
+instrukt-ai-logs teleclaude --since 10m --grep 'logger=teleclaude'
+
+# Follow (tail -f style) after printing the --since window
+instrukt-ai-logs teleclaude --since 10m --follow
+
+# Restrict to specific source streams (per-process files)
+instrukt-ai-logs teleclaude --since 1h --logs=cron,docs-watch
+```
+
+Without `--logs`, every `*.log*` file in the app directory is merged by
+timestamp (rotation suffixes included). With `--logs=stem1,stem2`, only files
+whose stem matches an entry are read — exact stem match, so `--logs=cron`
+picks `cron.log`, `cron.log.0`, `cron.log.1` and never `cron-backup.log`.
+Follow mode reads each selected file with one polling thread per file.

instruktai_python_logger-0.4.0/instrukt_ai_logging/__init__.py

@@ -0,0 +1,33 @@
+"""InstruktAI logging standard library.
+
+See `README.md` for usage and `docs/design.md` for design intent.
+"""
+
+__all__ = [
+    "__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
+
+    _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,
+    InstruktAILogger,
+    InstruktAILoggerProtocol,
+    resolve_log_file,
+    resolve_log_files,
+    TRACE,
+)

instruktai_python_logger-0.4.0/instrukt_ai_logging/cli.py

@@ -0,0 +1,224 @@
+from __future__ import annotations
+
+import argparse
+import os
+import re
+import sys
+import threading
+import time
+from pathlib import Path
+from typing import Iterator
+
+from instrukt_ai_logging.logging import (
+    iter_recent_log_lines_merged,
+    parse_since,
+    resolve_log_files,
+)
+
+
+def iter_follow_lines(
+    log_file: Path,
+    *,
+    poll_interval_s: float = 0.25,
+    start_at_end: bool = True,
+    max_lines: int | None = None,
+    max_seconds: float | None = None,
+) -> Iterator[str]:
+    """Yield new lines appended to `log_file`, similar to `tail -f`.
+
+    - Detects rotation (inode change) and truncation.
+    - Waits for file creation if it doesn't exist yet.
+    - `max_lines`/`max_seconds` are mainly for tests.
+    """
+    deadline = None if max_seconds is None else (time.monotonic() + max_seconds)
+    emitted = 0
+
+    f = None
+    inode = None
+    start_at_end_for_next_open = start_at_end
+
+    try:
+        while True:
+            if deadline is not None and time.monotonic() >= deadline:
+                return
+
+            if f is None:
+                try:
+                    f = log_file.open("r", encoding="utf-8", errors="replace")
+                except FileNotFoundError:
+                    time.sleep(poll_interval_s)
+                    continue
+
+                try:
+                    inode = os.fstat(f.fileno()).st_ino
+                except OSError:
+                    inode = None
+
+                if start_at_end_for_next_open:
+                    f.seek(0, os.SEEK_END)
+                else:
+                    f.seek(0, os.SEEK_SET)
+
+                # Only the first open may start at end; after rotation we read from start.
+                start_at_end_for_next_open = False
+
+            line = f.readline()
+            if line:
+                yield line
+                emitted += 1
+                if max_lines is not None and emitted >= max_lines:
+                    return
+                continue
+
+            # No new data: detect rotation/truncation and wait.
+            try:
+                st = log_file.stat()
+            except FileNotFoundError:
+                f.close()
+                f = None
+                inode = None
+                time.sleep(poll_interval_s)
+                continue
+
+            if inode is not None and getattr(st, "st_ino", None) is not None and st.st_ino != inode:
+                f.close()
+                f = None
+                inode = None
+                continue
+
+            if f.tell() > st.st_size:
+                f.seek(0, os.SEEK_SET)
+
+            time.sleep(poll_interval_s)
+    finally:
+        if f is not None:
+            try:
+                f.close()
+            except OSError:
+                pass
+
+
+def _parse_stems(value: str) -> list[str]:
+    return [item.strip() for item in value.split(",") if item.strip()]
+
+
+def _stem_of(path: Path) -> str:
+    """Return the stem before the first `.log` suffix (e.g. `cron.log.1` → `cron`)."""
+    name = path.name
+    idx = name.find(".log")
+    return name[:idx] if idx > 0 else name
+
+
+def _is_rotation_suffix(path: Path) -> bool:
+    """True for `<stem>.log.<n>` rotation files (and friends), false for `<stem>.log`."""
+    name = path.name
+    idx = name.find(".log")
+    return idx > 0 and name[idx + len(".log") :] != ""
+
+
+def main() -> None:
+    from instrukt_ai_logging import __version__
+
+    parser = argparse.ArgumentParser(prog="instrukt-ai-logs", add_help=True)
+    parser.add_argument(
+        "--version",
+        action="version",
+        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(
+        "-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(
+        "--logs",
+        default="",
+        help=(
+            "Comma-separated list of stems to include (e.g. 'cron,docs-watch'). "
+            "Default: all log files in the app's directory."
+        ),
+    )
+    args = parser.parse_args()
+
+    try:
+        since = parse_since(args.since)
+    except ValueError as e:
+        raise SystemExit(str(e)) from e
+
+    pattern = re.compile(args.grep) if args.grep else None
+    stems = _parse_stems(args.logs) or None
+
+    files = resolve_log_files(args.app, stems=stems)
+    if not files:
+        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 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 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

instruktai_python_logger-0.4.0/instrukt_ai_logging/install.py

@@ -0,0 +1,59 @@
+"""Install log rotation for InstruktAI logs."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from pathlib import Path
+
+
+def _write_file(path: Path, content: str, *, force: bool) -> None:
+    if path.exists() and not force:
+        raise SystemExit(f"Refusing to overwrite existing file: {path}. Use --force.")
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(content, encoding="utf-8")
+
+
+def _install_newsyslog(log_root: Path, *, force: bool) -> Path:
+    conf_path = Path("/etc/newsyslog.d/instrukt-ai.conf")
+    line = f"{log_root}/" + "*/*.log  640  10  100000  *  N\n"
+    _write_file(conf_path, line, force=force)
+    return conf_path
+
+
+def _install_logrotate(log_root: Path, *, force: bool) -> Path:
+    conf_path = Path("/etc/logrotate.d/instrukt-ai")
+    content = f"""{log_root}/*/*.log {{
+    size 100M
+    rotate 10
+    missingok
+    notifempty
+    copytruncate
+}}
+"""
+    _write_file(conf_path, content, force=force)
+    return conf_path
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(prog="instrukt-ai-log-setup", add_help=True)
+    parser.add_argument(
+        "--log-root",
+        default=os.environ.get("INSTRUKT_AI_LOG_ROOT", "/var/log/instrukt-ai"),
+        help="Base log root (default: /var/log/instrukt-ai or INSTRUKT_AI_LOG_ROOT)",
+    )
+    parser.add_argument("--force", action="store_true", help="Overwrite existing config")
+    args = parser.parse_args()
+
+    log_root = Path(args.log_root)
+    if sys.platform == "darwin":
+        conf = _install_newsyslog(log_root, force=args.force)
+    else:
+        conf = _install_logrotate(log_root, force=args.force)
+
+    sys.stdout.write(f"installed: {conf}\n")
+
+
+if __name__ == "__main__":
+    main()