@agentunion/kite 1.0.7 → 1.2.0

package/core/kite_log.py

@@ -0,0 +1,241 @@
+"""
+Kite module logging utilities.
+Provides latest.log + crashes.jsonl infrastructure per the 异常处理规范.
+
+Each module calls init_module_log() and setup_exception_hooks() at startup.
+All paths derived from KITE_MODULE_DATA environment variable.
+
+Note: This is a convenience library for Python modules. Node.js/binary modules
+implement the same spec independently (paths + formats are language-agnostic).
+"""
+
+import json
+import os
+import re
+import sys
+import threading
+import traceback
+from datetime import datetime, timezone
+
+
+# ── Module-level state (initialized by init_module_log) ──
+
+_module_name = ""
+_log_dir = None
+_log_latest_path = None
+_log_daily_path = None
+_log_daily_date = ""
+_crash_log_path = None
+_log_lock = threading.Lock()
+
+# Strip ANSI escape sequences for plain-text log files
+_ANSI_RE = re.compile(r"\033\[[0-9;]*m")
+
+
+def _strip_ansi(s: str) -> str:
+    return _ANSI_RE.sub("", s)
+
+
+def _resolve_daily_log_path():
+    """Resolve daily log path based on current date."""
+    global _log_daily_path, _log_daily_date
+    if not _log_dir:
+        return
+    today = datetime.now().strftime("%Y-%m-%d")
+    if today == _log_daily_date and _log_daily_path:
+        return
+    month_dir = os.path.join(_log_dir, today[:7])
+    os.makedirs(month_dir, exist_ok=True)
+    _log_daily_path = os.path.join(month_dir, f"{today}.log")
+    _log_daily_date = today
+
+
+def init_module_log(module_name: str):
+    """Initialize log files for a module. Call once at startup.
+
+    Requires KITE_MODULE_DATA environment variable to be set.
+    Creates: {KITE_MODULE_DATA}/log/latest.log (truncated)
+             {KITE_MODULE_DATA}/log/crashes.jsonl (truncated)
+             {KITE_MODULE_DATA}/log/{YYYY-MM}/ (daily archive directory)
+    """
+    global _module_name, _log_dir, _log_latest_path, _crash_log_path
+
+    _module_name = module_name
+    module_data = os.environ.get("KITE_MODULE_DATA")
+    if not module_data:
+        return
+
+    _log_dir = os.path.join(module_data, "log")
+    os.makedirs(_log_dir, exist_ok=True)
+
+    suffix = os.environ.get("KITE_INSTANCE_SUFFIX", "")
+
+    # latest.log — truncate on each startup
+    _log_latest_path = os.path.join(_log_dir, f"latest{suffix}.log")
+    try:
+        with open(_log_latest_path, "w", encoding="utf-8") as f:
+            pass
+    except Exception:
+        _log_latest_path = None
+
+    # crashes.jsonl — truncate on each startup
+    _crash_log_path = os.path.join(_log_dir, f"crashes{suffix}.jsonl")
+    try:
+        with open(_crash_log_path, "w", encoding="utf-8") as f:
+            pass
+    except Exception:
+        _crash_log_path = None
+
+    # Ensure daily archive directory exists
+    _resolve_daily_log_path()
+
+
+def write_log(plain_line: str):
+    """Write a plain-text line to both latest.log and daily log (open-write-close)."""
+    with _log_lock:
+        if _log_latest_path:
+            try:
+                with open(_log_latest_path, "a", encoding="utf-8") as f:
+                    f.write(plain_line)
+            except Exception:
+                pass
+        _resolve_daily_log_path()
+        if _log_daily_path:
+            try:
+                with open(_log_daily_path, "a", encoding="utf-8") as f:
+                    f.write(plain_line)
+            except Exception:
+                pass
+
+
+def write_crash(exc_type, exc_value, exc_tb,
+                thread_name=None, severity="critical", handled=False):
+    """Write crash record to crashes.jsonl + daily crash archive."""
+    record = {
+        "timestamp": datetime.now(timezone.utc).isoformat(),
+        "module": _module_name,
+        "thread": thread_name or threading.current_thread().name,
+        "exception_type": exc_type.__name__ if exc_type else "Unknown",
+        "exception_message": str(exc_value),
+        "traceback": "".join(traceback.format_exception(exc_type, exc_value, exc_tb)),
+        "severity": severity,
+        "handled": handled,
+        "process_id": os.getpid(),
+        "platform": sys.platform,
+        "runtime_version": f"Python {sys.version.split()[0]}",
+    }
+
+    if exc_tb:
+        tb_entries = traceback.extract_tb(exc_tb)
+        if tb_entries:
+            last = tb_entries[-1]
+            record["context"] = {
+                "function": last.name,
+                "file": os.path.basename(last.filename),
+                "line": last.lineno,
+            }
+
+    line = json.dumps(record, ensure_ascii=False) + "\n"
+
+    # 1. Write to crashes.jsonl (current run)
+    if _crash_log_path:
+        try:
+            with open(_crash_log_path, "a", encoding="utf-8") as f:
+                f.write(line)
+        except Exception:
+            pass
+
+    # 2. Write to daily crash archive
+    if _log_dir:
+        try:
+            today = datetime.now().strftime("%Y-%m-%d")
+            archive_dir = os.path.join(_log_dir, "crashes", today[:7])
+            os.makedirs(archive_dir, exist_ok=True)
+            archive_path = os.path.join(archive_dir, f"{today}.jsonl")
+            with open(archive_path, "a", encoding="utf-8") as f:
+                f.write(line)
+        except Exception:
+            pass
+
+
+def print_crash_summary(exc_type, exc_tb, thread_name=None):
+    """Print crash summary to console (red highlight)."""
+    RED = "\033[91m"
+    RESET = "\033[0m"
+
+    if exc_tb:
+        tb_entries = traceback.extract_tb(exc_tb)
+        if tb_entries:
+            last = tb_entries[-1]
+            location = f"{os.path.basename(last.filename)}:{last.lineno}"
+        else:
+            location = "unknown"
+    else:
+        location = "unknown"
+
+    prefix = f"[{_module_name}]"
+    if thread_name:
+        print(f"{prefix} {RED}线程 {thread_name} 崩溃: "
+              f"{exc_type.__name__} in {location}{RESET}")
+    else:
+        print(f"{prefix} {RED}崩溃: {exc_type.__name__} in {location}{RESET}")
+    if _crash_log_path:
+        print(f"{prefix} 崩溃日志: {_crash_log_path}")
+
+
+def setup_exception_hooks(module_name: str = ""):
+    """Set up global exception hooks (sys.excepthook + threading.excepthook).
+    Call once at startup after init_module_log().
+    """
+    if module_name:
+        global _module_name
+        _module_name = module_name
+
+    _orig_excepthook = sys.excepthook
+
+    def _excepthook(exc_type, exc_value, exc_tb):
+        write_crash(exc_type, exc_value, exc_tb, severity="critical", handled=False)
+        print_crash_summary(exc_type, exc_tb)
+        _orig_excepthook(exc_type, exc_value, exc_tb)
+
+    sys.excepthook = _excepthook
+
+    if hasattr(threading, "excepthook"):
+        def _thread_excepthook(args):
+            write_crash(args.exc_type, args.exc_value, args.exc_traceback,
+                        thread_name=args.thread.name if args.thread else "unknown",
+                        severity="error", handled=False)
+            print_crash_summary(args.exc_type, args.exc_traceback,
+                                thread_name=args.thread.name if args.thread else None)
+
+        threading.excepthook = _thread_excepthook
+
+
+def install_log_hook():
+    """Install a hook on the _SafeWriter or stdout to capture all print output
+    to latest.log + daily log. Call after init_module_log().
+
+    Wraps the current sys.stdout so that every write() also goes to log files.
+    """
+    if not _log_latest_path:
+        return
+
+    original_stdout = sys.stdout
+
+    class _LoggingWriter:
+        """Wraps stdout to tee all output to log files."""
+        def __init__(self, stream):
+            self._stream = stream
+
+        def write(self, s):
+            self._stream.write(s)
+            if s and s.strip():
+                write_log(_strip_ansi(s) + ("\n" if not s.endswith("\n") else ""))
+
+        def flush(self):
+            self._stream.flush()
+
+        def __getattr__(self, name):
+            return getattr(self._stream, name)
+
+    sys.stdout = _LoggingWriter(original_stdout)