instruktai-python-logger 0.1.0__py3-none-any.whl

instrukt_ai_logging/__init__.py

@@ -0,0 +1,14 @@
+"""InstruktAI logging standard library.
+
+See `README.md` for usage and `docs/design.md` for design intent.
+"""
+
+__all__ = [
+    "__version__",
+    "configure_logging",
+    "log_kv",
+]
+
+__version__ = "0.0.0"
+
+from instrukt_ai_logging.logging import configure_logging, log_kv  # noqa: E402  (intentional re-export)

instrukt_ai_logging/cli.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from pathlib import Path
+
+from instrukt_ai_logging.logging import (
+    _fallback_log_root,
+    _resolve_log_root,
+    iter_recent_log_lines,
+    parse_since,
+)
+
+
+def _resolve_log_file(app: str) -> Path:
+    primary_dir = _resolve_log_root(app)
+    primary_file = primary_dir / f"{app}.log"
+    if primary_file.exists():
+        return primary_file
+
+    fallback_dir = _fallback_log_root(app)
+    fallback_file = fallback_dir / f"{app}.log"
+    if fallback_file.exists():
+        return fallback_file
+
+    return primary_file
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(prog="instrukt-ai-logs", add_help=True)
+    parser.add_argument("app", help="App/service name (folder and filename stem)")
+    parser.add_argument(
+        "--since", default="10m", help="Time window (e.g. 10m, 2h, 1d). Default: 10m"
+    )
+    parser.add_argument("--grep", default="", help="Regex to filter lines (optional)")
+    args = parser.parse_args()
+
+    try:
+        since = parse_since(args.since)
+    except ValueError as e:
+        raise SystemExit(str(e)) from e
+
+    log_file = _resolve_log_file(args.app)
+    if not log_file.exists():
+        raise SystemExit(f"Log file not found: {log_file}")
+
+    pattern = re.compile(args.grep) if args.grep else None
+    for line in iter_recent_log_lines(log_file, since):
+        if pattern and not pattern.search(line):
+            continue
+        sys.stdout.write(line)

instrukt_ai_logging/logging.py

@@ -0,0 +1,366 @@
+from __future__ import annotations
+
+import logging
+import os
+import re
+import sys
+from collections.abc import Mapping
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+from logging.handlers import WatchedFileHandler
+from pathlib import Path
+from typing import Any
+
+
+def _level_name_to_int(level_name: str, default: int) -> int:
+    name = level_name.strip().upper()
+    if not name:
+        return default
+    candidate: object = getattr(logging, name, None)
+    if isinstance(candidate, int):
+        return candidate
+    return default
+
+
+def _parse_csv(value: str) -> list[str]:
+    return [item.strip() for item in value.split(",") if item.strip()]
+
+
+def _now_utc() -> datetime:
+    return datetime.now(tz=timezone.utc)
+
+
+class UtcMillisFormatter(logging.Formatter):
+    def formatTime(self, record: logging.LogRecord, datefmt: str | None = None) -> str:
+        dt = datetime.fromtimestamp(record.created, tz=timezone.utc)
+        if datefmt:
+            return dt.strftime(datefmt)
+        return dt.strftime("%Y-%m-%dT%H:%M:%S") + f".{int(record.msecs):03d}Z"
+
+
+_SAFE_BARE_VALUE = re.compile(r"^[A-Za-z0-9._/:+-]+$")
+_SAFE_KEY = re.compile(r"^[A-Za-z_][A-Za-z0-9_.-]*$")
+
+# Keep this small and high-signal; expand only with strong justification.
+_REDACTION_PATTERNS: list[tuple[re.Pattern[str], str]] = [
+    # Telegram bot token in API URLs: https://api.telegram.org/bot<token>/...
+    (re.compile(r"(api\\.telegram\\.org/bot)([^/\\s]+)"), r"\\1<REDACTED>"),
+    # Generic Bearer token
+    (re.compile(r"\\bBearer\\s+[^\\s]+"), "Bearer <REDACTED>"),
+    # Common OpenAI-style key prefix (avoid leaking)
+    (re.compile(r"\\bsk-[A-Za-z0-9]{10,}\\b"), "sk-<REDACTED>"),
+]
+
+
+def _redact_text(text: str) -> str:
+    redacted = text
+    for pattern, replacement in _REDACTION_PATTERNS:
+        redacted = pattern.sub(replacement, redacted)
+    return redacted
+
+
+def _truncate_text(text: str, max_chars: int) -> str:
+    if max_chars > 0 and len(text) > max_chars:
+        return text[:max_chars] + "…(truncated)"
+    return text
+
+
+def _escape_quotes(value: str) -> str:
+    return value.replace("\\", "\\\\").replace('"', '\\"').replace("\n", "\\n").replace("\r", "\\r")
+
+
+def _format_logfmt_value(value: object, *, max_chars: int) -> str:
+    if value is None:
+        return "null"
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, (int, float)):
+        return str(value)
+
+    text = _redact_text(str(value))
+    text = _truncate_text(text, max_chars=max_chars)
+
+    if _SAFE_BARE_VALUE.fullmatch(text):
+        return text
+    return f'"{_escape_quotes(text)}"'
+
+
+def _format_logfmt_string(text: str, *, max_chars: int, force_quote: bool) -> str:
+    redacted = _redact_text(text)
+    redacted = _truncate_text(redacted, max_chars=max_chars)
+    if not force_quote and _SAFE_BARE_VALUE.fullmatch(redacted):
+        return redacted
+    return f'"{_escape_quotes(redacted)}"'
+
+
+class LogfmtFormatter(UtcMillisFormatter):
+    """Single-line logfmt-ish formatter.
+
+    Always emits key/value pairs with at least:
+      level=..., logger=..., msg="..."
+
+    Optional additional pairs can be attached via `extra={"kv": {...}}`.
+    """
+
+    def __init__(self, max_message_chars: int) -> None:
+        super().__init__(datefmt=None)
+        self.max_message_chars = max_message_chars
+
+    def format(self, record: logging.LogRecord) -> str:
+        ts = self.formatTime(record)
+        try:
+            message = record.getMessage()
+        except Exception:
+            message = "<unprintable>"
+
+        parts = [
+            ts,
+            f"level={_format_logfmt_value(record.levelname, max_chars=self.max_message_chars)}",
+            f"logger={_format_logfmt_value(record.name, max_chars=self.max_message_chars)}",
+            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)):
+                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)}"
+                )
+
+        if record.exc_info:
+            try:
+                exc_text = self.formatException(record.exc_info).replace("\n", "\\n")
+            except Exception:
+                exc_text = "<exception>"
+            parts.append(f"exc={_format_logfmt_value(exc_text, max_chars=self.max_message_chars)}")
+
+        return " ".join(parts)
+
+
+def log_kv(logger: logging.Logger, level: int, data: Mapping[str, Any]) -> None:
+    """Log a key/value event.
+
+    `data` MUST include `msg` and may include any other serializable values.
+    """
+    if "msg" not in data:
+        raise ValueError('log_kv requires a "msg" key')
+
+    msg = str(data["msg"])
+    kv: dict[str, object] = {}
+    for key, value in data.items():
+        if key == "msg":
+            continue
+        if not _SAFE_KEY.fullmatch(key):
+            raise ValueError(f"Invalid key for log_kv: {key!r}")
+        kv[key] = value
+
+    logger.log(level, msg, extra={"kv": kv})
+
+
+class _ThirdPartySelectorFilter(logging.Filter):
+    """Enforce third-party spotlight semantics on a handler.
+
+    - Always allow records from `app_logger_prefix`.
+    - For non-app loggers:
+      - If `spotlight_prefixes` is empty: allow (level gating happens via logger levels).
+      - If `spotlight_prefixes` is set: only allow records whose logger name starts with one of them.
+    """
+
+    def __init__(self, app_logger_prefix: str, spotlight_prefixes: tuple[str, ...]) -> None:
+        super().__init__()
+        self.app_logger_prefix = app_logger_prefix
+        self.spotlight_prefixes = spotlight_prefixes
+
+    def filter(self, record: logging.LogRecord) -> bool:  # noqa: A003
+        name = record.name
+        if name == self.app_logger_prefix or name.startswith(self.app_logger_prefix + "."):
+            return True
+        if not self.spotlight_prefixes:
+            return True
+        return any(name == p or name.startswith(p + ".") for p in self.spotlight_prefixes)
+
+
+@dataclass(frozen=True)
+class LoggingContract:
+    env_prefix: str
+    app_logger_prefix: str
+    app_name: str
+
+    @property
+    def env_log_level(self) -> str:
+        return f"{self.env_prefix}_LOG_LEVEL"
+
+    @property
+    def env_third_party_level(self) -> str:
+        return f"{self.env_prefix}_THIRD_PARTY_LOG_LEVEL"
+
+    @property
+    def env_third_party_loggers(self) -> str:
+        return f"{self.env_prefix}_THIRD_PARTY_LOGGERS"
+
+
+def _resolve_log_root(app_name: str) -> Path:
+    override = os.getenv("INSTRUKT_AI_LOG_ROOT")
+    if override:
+        return Path(override).expanduser()
+    return Path("/var/log/instrukt-ai") / app_name
+
+
+def _fallback_log_root(app_name: str) -> Path:
+    # Deterministic fallback: repo-local ./logs if available, else /tmp.
+    candidate = Path.cwd() / "logs"
+    if candidate.exists() or candidate.parent.exists():
+        return candidate
+    return Path("/tmp") / "instrukt-ai" / app_name
+
+
+def _ensure_log_dir(log_dir: Path) -> None:
+    log_dir.mkdir(parents=True, exist_ok=True)
+
+
+def configure_logging(
+    *,
+    env_prefix: str,
+    app_logger_prefix: str,
+    app_name: str,
+    log_filename: str | None = None,
+    max_message_chars: int = 4000,
+) -> Path:
+    """Configure logging according to the InstruktAI contract.
+
+    Returns the resolved log file path in use.
+    """
+    contract = LoggingContract(
+        env_prefix=env_prefix,
+        app_logger_prefix=app_logger_prefix,
+        app_name=app_name,
+    )
+
+    our_level_name = (os.getenv(contract.env_log_level) or "INFO").upper()
+    third_party_level_name = (os.getenv(contract.env_third_party_level) or "WARNING").upper()
+    spotlight = _parse_csv(os.getenv(contract.env_third_party_loggers, ""))
+
+    our_level = _level_name_to_int(our_level_name, logging.INFO)
+    third_party_level = _level_name_to_int(third_party_level_name, logging.WARNING)
+
+    # Root logger governs all loggers that don't explicitly set a level.
+    root_level = third_party_level if not spotlight else logging.WARNING
+
+    log_dir = _resolve_log_root(app_name)
+    try:
+        _ensure_log_dir(log_dir)
+    except (PermissionError, OSError):
+        log_dir = _fallback_log_root(app_name)
+        _ensure_log_dir(log_dir)
+
+    log_file = log_dir / (log_filename or f"{app_name}.log")
+
+    formatter = LogfmtFormatter(max_message_chars=max_message_chars)
+
+    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)
+        )
+    )
+
+    # Configure root.
+    logging.root.handlers = [handler]
+    logging.root.setLevel(root_level)
+
+    # Configure our logs.
+    logging.getLogger(app_logger_prefix).setLevel(our_level)
+
+    # Configure spotlight third-party prefixes (only affects non-app loggers).
+    for prefix in spotlight:
+        if prefix == app_logger_prefix or prefix.startswith(app_logger_prefix + "."):
+            continue
+        logging.getLogger(prefix).setLevel(third_party_level)
+
+    # Optional console output for interactive runs only.
+    if sys.stdout.isatty():  # type: ignore[misc]
+        console = logging.StreamHandler()
+        console.setLevel(logging.NOTSET)
+        console.setFormatter(formatter)
+        console.addFilter(
+            _ThirdPartySelectorFilter(
+                app_logger_prefix=app_logger_prefix,
+                spotlight_prefixes=tuple(spotlight),
+            )
+        )
+        logging.root.addHandler(console)
+
+    return log_file
+
+
+def parse_since(value: str) -> timedelta:
+    """Parse durations like '10m', '2h', '1d', '30s'."""
+    raw = value.strip().lower()
+    if not raw:
+        raise ValueError("Empty duration")
+    unit = raw[-1]
+    number = raw[:-1]
+    if not number.isdigit():
+        raise ValueError(f"Invalid duration: {value}")
+    n = int(number)
+    if unit == "s":
+        return timedelta(seconds=n)
+    if unit == "m":
+        return timedelta(minutes=n)
+    if unit == "h":
+        return timedelta(hours=n)
+    if unit == "d":
+        return timedelta(days=n)
+    raise ValueError(f"Invalid duration unit: {unit}")
+
+
+def parse_log_timestamp(line: str) -> datetime | None:
+    """Parse the timestamp at the start of a standard log line.
+
+    Expected: YYYY-MM-DDTHH:MM:SS.mmmZ ...
+    """
+    token = line.split(" ", 1)[0].strip()
+    if not token.endswith("Z"):
+        return None
+    try:
+        # Python doesn't accept 'Z' directly in fromisoformat.
+        return datetime.fromisoformat(token.replace("Z", "+00:00"))
+    except ValueError:
+        return None
+
+
+def iter_recent_log_lines(log_file: Path, since: timedelta) -> list[str]:
+    """Return log lines newer than now-`since`, reading rotated siblings when present."""
+    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")
+        ],
+        key=lambda p: p.stat().st_mtime,
+    )
+
+    lines: list[str] = []
+    for path in candidates:
+        try:
+            with path.open("r", encoding="utf-8", errors="replace") as f:
+                for line in f:
+                    ts = parse_log_timestamp(line)
+                    if ts is None:
+                        continue
+                    if ts >= cutoff:
+                        lines.append(line)
+        except FileNotFoundError:
+            continue
+
+    return lines

instruktai_python_logger-0.1.0.dist-info/METADATA

@@ -0,0 +1,58 @@
+Metadata-Version: 2.4
+Name: instruktai-python-logger
+Version: 0.1.0
+Summary: Centralized logging utilities for InstruktAI 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 InstruktAI 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 instruktai-python-logger
+```
+
+From GitHub:
+
+```bash
+pip install git+ssh://git@github.com/InstruktAI/python-logger.git
+```
+
+## API
+
+- Python entrypoint: `instrukt_ai_logging.configure_logging(...)`
+- Structured logging helper: `instrukt_ai_logging.log_kv(logger, level, {"msg": "...", ...})`
+- CLI entrypoint: `instrukt-ai-logs` (reads recent log lines)
+
+## 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, e.g. `httpcore,telegram`)
+
+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`.

instruktai_python_logger-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+instrukt_ai_logging/__init__.py,sha256=WB5L0Qrl-NSDvVrrAtyrdZp2Ajm5aqAxWeZtS2f8KLk,313
+instrukt_ai_logging/cli.py,sha256=XvcCqiyOlpugzbG0QfNqrQsT0eOemxJEfJRqUff9x4k,1485
+instrukt_ai_logging/logging.py,sha256=bKlh9l92wYRY45w-ktliP8vAQqn4NrbUOXNKQkKXVa4,11893
+instruktai_python_logger-0.1.0.dist-info/METADATA,sha256=yiyFgfIq0U7W4uU1P-7FNmMsV7nmCPNvEhwfiHldzls,1781
+instruktai_python_logger-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+instruktai_python_logger-0.1.0.dist-info/entry_points.txt,sha256=Xq2g8G8Rqec3wUGKa7OOCedBTYMFvrddQh4g4PpS7cE,66
+instruktai_python_logger-0.1.0.dist-info/top_level.txt,sha256=SkmwrXO5PioZPGXZeHwfjigT-3_RFqRiwemou6jPc34,20
+instruktai_python_logger-0.1.0.dist-info/RECORD,,

instruktai_python_logger-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

instruktai_python_logger-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+instrukt-ai-logs = instrukt_ai_logging.cli:main

instruktai_python_logger-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+instrukt_ai_logging