logs.py 13 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350
  1. """``hermes logs`` — view and filter Hermes log files.
  2. Supports tailing, following, session filtering, level filtering,
  3. component filtering, and relative time ranges. All log files live
  4. under ``~/.hermes/logs/``.
  5. Usage examples::
  6. hermes logs # last 50 lines of agent.log
  7. hermes logs -f # follow agent.log in real time
  8. hermes logs errors # last 50 lines of errors.log
  9. hermes logs gateway -n 100 # last 100 lines of gateway.log
  10. hermes logs gui -f # follow gui.log (dashboard/pty/ws)
  11. hermes logs desktop -f # follow desktop.log (Electron app boot/backend)
  12. hermes logs update # last 50 lines of update.log (hermes update mirror)
  13. hermes logs handoff # last 50 lines of desktop-update-handoff.log
  14. hermes logs --level WARNING # only WARNING+ lines
  15. hermes logs --session abc123 # filter by session ID substring
  16. hermes logs --component tools # only tool-related lines
  17. hermes logs --since 1h # lines from the last hour
  18. hermes logs --since 30m -f # follow, starting 30 min ago
  19. """
  20. import re
  21. import sys
  22. import time
  23. from datetime import datetime, timedelta
  24. from pathlib import Path
  25. from typing import Optional, Sequence
  26. from hermes_constants import display_hermes_home, get_default_hermes_root, get_hermes_home
  27. # Known log files (name → filename)
  28. LOG_FILES = {
  29. "agent": "agent.log",
  30. "errors": "errors.log",
  31. "gateway": "gateway.log",
  32. "gui": "gui.log",
  33. "desktop": "desktop.log",
  34. # Full stdout/stderr mirror of the last `hermes update` runs (written by
  35. # hermes_cli.main's _UpdateOutputStream; append-only across runs). When a
  36. # Desktop-driven update fails at the Electron rebuild the ONLY artifacts
  37. # holding the root cause are this file and the hand-off log below, so
  38. # `hermes logs list` (a directory scan) showing them without readable
  39. # keys was an inconsistency of its own.
  40. "update": "update.log",
  41. # Desktop-driven update hand-off (scripts/desktop-update/windows.ps1 +
  42. # posix.sh): stage log including the `desktop --force-build --build-only`
  43. # retry stderr.
  44. "handoff": "desktop-update-handoff.log",
  45. # Every stdio MCP subprocess's stderr (tools/mcp_tool.py redirects it
  46. # here, with per-server session markers) — the "MCP output channel".
  47. "mcp": "mcp-stderr.log",
  48. }
  49. # Written to the ROOT home whatever profile is active: ``hermes update`` mutates the checkout every
  50. # profile shares, and its mirror (main_dashboard) + the Desktop hand-off scripts write <root>/logs.
  51. ROOT_HOME_LOGS = frozenset({"update", "handoff"})
  52. def log_file_path(log_name: str) -> Optional[Path]:
  53. """Where *log_name* lives (doesn't check existence); None for an unknown name."""
  54. filename = LOG_FILES.get(log_name)
  55. if filename is None:
  56. return None
  57. home = get_default_hermes_root() if log_name in ROOT_HOME_LOGS else get_hermes_home()
  58. return home / "logs" / filename
  59. # "2026-04-05 22:35:00[,123]" at the start of a line; update.log /
  60. # desktop-update-handoff.log stamp with the shell's ISO-8601 "T" shape
  61. # ("2026-09-29T21:36:18+08:00", "=== hermes update started 2026-09-29T21:36:18 ===").
  62. _TS_RE = re.compile(r"(\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}:\d{2})")
  63. _LEVEL_RE = re.compile(r"\s(DEBUG|INFO|WARNING|ERROR|CRITICAL)\s")
  64. # Logger name: the token before ":" after the level and optional "[session]" tag,
  65. # e.g. "INFO gateway.run:" or "INFO [sess_abc] tools.terminal_tool:".
  66. _LOGGER_NAME_RE = re.compile(r"\s(?:DEBUG|INFO|WARNING|ERROR|CRITICAL)(?:\s+\[.*?\])?\s+(\S+):")
  67. _LEVEL_ORDER = {"DEBUG": 0, "INFO": 1, "WARNING": 2, "ERROR": 3, "CRITICAL": 4}
  68. def _parse_since(since_str: str) -> Optional[datetime]:
  69. """Parse a relative time like '1h', '30m', '2d' into a cutoff; None if unparseable."""
  70. match = re.match(r"^(\d+)\s*([smhd])$", since_str.strip().lower())
  71. if not match:
  72. return None
  73. unit = {"s": "seconds", "m": "minutes", "h": "hours", "d": "days"}[match.group(2)]
  74. return datetime.now() - timedelta(**{unit: int(match.group(1))})
  75. def _parse_line_timestamp(line: str) -> Optional[datetime]:
  76. m = _TS_RE.search(line)
  77. if not m:
  78. return None
  79. try:
  80. return datetime.strptime(m.group(1).replace("T", " "), "%Y-%m-%d %H:%M:%S")
  81. except ValueError:
  82. return None
  83. def _extract_level(line: str) -> Optional[str]:
  84. m = _LEVEL_RE.search(line)
  85. return m.group(1) if m else None
  86. def _extract_logger_name(line: str) -> Optional[str]:
  87. m = _LOGGER_NAME_RE.search(line)
  88. return m.group(1) if m else None
  89. def _line_matches_component(line: str, prefixes: Sequence[str]) -> bool:
  90. name = _extract_logger_name(line)
  91. return name is not None and name.startswith(tuple(prefixes))
  92. def _matches_filters(
  93. line: str,
  94. *,
  95. min_level: Optional[str] = None,
  96. session_filter: Optional[str] = None,
  97. since: Optional[datetime] = None,
  98. component_prefixes: Optional[Sequence[str]] = None,
  99. ) -> bool:
  100. """Whether one line passes all active filters (a line without a timestamp/level passes those);
  101. ``_LineFilter`` decides for unstamped continuation lines."""
  102. if since is not None:
  103. ts = _parse_line_timestamp(line)
  104. if ts is not None and ts < since:
  105. return False
  106. if min_level is not None:
  107. level = _extract_level(line)
  108. if level is not None and _LEVEL_ORDER.get(level, 0) < _LEVEL_ORDER.get(min_level, 0):
  109. return False
  110. if session_filter is not None and session_filter not in line:
  111. return False
  112. return component_prefixes is None or _line_matches_component(line, component_prefixes)
  113. class _LineFilter:
  114. """Stateful ``_matches_filters`` over consecutive lines of one file. A line with no stamp continues
  115. the record above it (traceback frames, multi-line messages), so it takes that record's verdict."""
  116. def __init__(self, **filters):
  117. self._filters = filters
  118. self._carry: Optional[bool] = None
  119. def __call__(self, line: str) -> bool:
  120. if _parse_line_timestamp(line) is not None:
  121. self._carry = _matches_filters(line, **self._filters)
  122. elif self._carry is None:
  123. # Before the first stamp: this record's time and level are unknown.
  124. timed = self._filters.get("since") is not None or self._filters.get("min_level") is not None
  125. return not timed and _matches_filters(line, **self._filters)
  126. return self._carry
  127. def tail_log(
  128. log_name: str = "agent",
  129. *,
  130. num_lines: int = 50,
  131. follow: bool = False,
  132. level: Optional[str] = None,
  133. session: Optional[str] = None,
  134. since: Optional[str] = None,
  135. component: Optional[str] = None,
  136. ) -> None:
  137. """Read and display log lines, optionally following in real time.
  138. Parameters
  139. ----------
  140. log_name
  141. Which log to read: ``"agent"``, ``"errors"``, ``"gateway"``, ``"gui"``,
  142. ``"desktop"``, ``"update"``, ``"handoff"``.
  143. num_lines
  144. Number of recent lines to show (before follow starts).
  145. follow
  146. If True, keep watching for new lines (Ctrl+C to stop).
  147. level
  148. Minimum log level to show (e.g. ``"WARNING"``).
  149. session
  150. Session ID substring to filter on.
  151. since
  152. Relative time string (e.g. ``"1h"``, ``"30m"``).
  153. component
  154. Component name to filter by (e.g. ``"gateway"``, ``"tools"``).
  155. """
  156. filename = LOG_FILES.get(log_name)
  157. if filename is None:
  158. print(f"Unknown log: {log_name!r}. Available: {', '.join(sorted(LOG_FILES))}")
  159. sys.exit(1)
  160. log_path = log_file_path(log_name)
  161. if not log_path.exists():
  162. print(f"Log file not found: {log_path}")
  163. print("(Logs are created when Hermes runs — try 'hermes chat' first)")
  164. sys.exit(1)
  165. since_dt = None
  166. if since:
  167. since_dt = _parse_since(since)
  168. if since_dt is None:
  169. print(f"Invalid --since value: {since!r}. Use format like '1h', '30m', '2d'.")
  170. sys.exit(1)
  171. min_level = level.upper() if level else None
  172. if min_level and min_level not in _LEVEL_ORDER:
  173. print(f"Invalid --level: {level!r}. Use DEBUG, INFO, WARNING, ERROR, or CRITICAL.")
  174. sys.exit(1)
  175. component_prefixes = None
  176. if component:
  177. from hermes_logging import COMPONENT_PREFIXES
  178. component_lower = component.lower()
  179. if component_lower not in COMPONENT_PREFIXES:
  180. available = ", ".join(sorted(COMPONENT_PREFIXES))
  181. print(f"Unknown component: {component!r}. Available: {available}")
  182. sys.exit(1)
  183. component_prefixes = COMPONENT_PREFIXES[component_lower]
  184. filters = dict(min_level=min_level, session_filter=session,
  185. since=since_dt, component_prefixes=component_prefixes)
  186. has_filters = any(v is not None for v in filters.values())
  187. try:
  188. lines = _read_tail(log_path, num_lines, has_filters=has_filters, **filters)
  189. except PermissionError:
  190. print(f"Permission denied: {log_path}")
  191. sys.exit(1)
  192. filter_parts = [
  193. f"{label}={value}" for label, value in
  194. (("level>", min_level), ("session", session), ("component", component), ("since", since))
  195. if value
  196. ]
  197. filter_desc = f" [{', '.join(filter_parts)}]" if filter_parts else ""
  198. mode = "Ctrl+C to stop" if follow else f"last {num_lines}"
  199. print(f"--- {display_hermes_home()}/logs/{filename}{filter_desc} ({mode}) ---")
  200. for line in lines:
  201. print(line, end="")
  202. if not follow:
  203. return
  204. try:
  205. _follow_log(log_path, **filters)
  206. except KeyboardInterrupt:
  207. print("\n--- stopped ---")
  208. def _read_tail(path: Path, num_lines: int, *, has_filters: bool = False, **filters) -> list:
  209. """Read the last *num_lines* matching lines; ``filters`` are ``_matches_filters`` kwargs."""
  210. if not has_filters:
  211. return _read_last_n_lines(path, num_lines)
  212. # Over-read so enough lines survive filtering.
  213. raw_lines = _read_last_n_lines(path, max(num_lines * 20, 2000))
  214. keep = _LineFilter(**filters)
  215. return [l for l in raw_lines if keep(l)][-num_lines:]
  216. def _read_all_lines(path: Path) -> list:
  217. with open(path, "r", encoding="utf-8-sig", errors="replace") as f:
  218. return f.readlines()
  219. def _read_last_n_lines(path: Path, n: int) -> list:
  220. """Read the last N lines; files over 1MB are read in growing chunks from the end."""
  221. try:
  222. size = path.stat().st_size
  223. if size == 0:
  224. return []
  225. if size <= 1_048_576:
  226. return _read_all_lines(path)[-n:]
  227. with open(path, "rb") as f:
  228. chunk_size = 8192
  229. lines = []
  230. pos = size
  231. while pos > 0 and len(lines) <= n + 1:
  232. read_size = min(chunk_size, pos)
  233. pos -= read_size
  234. f.seek(pos)
  235. chunk_lines = f.read(read_size).split(b"\n")
  236. if lines:
  237. # Join the chunk's trailing partial line with our leading partial line.
  238. lines[0] = chunk_lines[-1] + lines[0]
  239. lines = chunk_lines[:-1] + lines
  240. else:
  241. lines = chunk_lines
  242. chunk_size = min(chunk_size * 2, 65536)
  243. decoded = [raw.decode("utf-8", errors="replace") + "\n" for raw in lines if raw.strip()]
  244. return decoded[-n:]
  245. except Exception:
  246. return _read_all_lines(path)[-n:]
  247. def _follow_log(path: Path, **filters) -> None:
  248. """Poll a log file for new content and print matching lines."""
  249. keep = _LineFilter(**filters)
  250. with open(path, "r", encoding="utf-8-sig", errors="replace") as f:
  251. # Seek to end
  252. f.seek(0, 2)
  253. while True:
  254. line = f.readline()
  255. if not line:
  256. time.sleep(0.3)
  257. elif keep(line):
  258. print(line, end="")
  259. sys.stdout.flush()
  260. def _size_label(size: int) -> str:
  261. if size < 1024:
  262. return f"{size}B"
  263. if size < 1024 * 1024:
  264. return f"{size / 1024:.1f}KB"
  265. return f"{size / (1024 * 1024):.1f}MB"
  266. def _age_label(mtime: datetime) -> str:
  267. age_s = (datetime.now() - mtime).total_seconds()
  268. if age_s < 60:
  269. return "just now"
  270. if age_s < 3600:
  271. return f"{int(age_s / 60)}m ago"
  272. if age_s < 86400:
  273. return f"{int(age_s / 3600)}h ago"
  274. return mtime.strftime("%Y-%m-%d")
  275. def list_logs() -> None:
  276. """Print available log files with sizes (plus the root home's update logs under a profile)."""
  277. log_dir = get_hermes_home() / "logs"
  278. root_logs = [path for name in sorted(ROOT_HOME_LOGS)
  279. if (path := log_file_path(name)).parent != log_dir and path.is_file()]
  280. if not log_dir.exists() and not root_logs:
  281. print(f"No logs directory at {display_hermes_home()}/logs/")
  282. return
  283. print(f"Log files in {display_hermes_home()}/logs/:\n")
  284. found = False
  285. entries = sorted(log_dir.iterdir()) if log_dir.exists() else []
  286. for entry in [*entries, *root_logs]:
  287. if entry.is_file() and entry.suffix == ".log":
  288. st = entry.stat()
  289. age_str = _age_label(datetime.fromtimestamp(st.st_mtime))
  290. label = entry.name if entry.parent == log_dir else f"{entry.name} (root)"
  291. print(f" {label:<25} {_size_label(st.st_size):>8} {age_str}")
  292. found = True
  293. if not found:
  294. print(" (no log files yet — run 'hermes chat' to generate logs)")