eventlog.py 9.2 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191
  1. """Structured logging with steady-state silence for the LSP layer.
  2. LSP fires on every write_file/patch, so the level model keeps ``agent.log`` greppable
  3. (``rg 'lsp\\['``) without noise: DEBUG for steady-state events with no novel signal (clean,
  4. skipped, repeat "no project root" / "server unavailable"); INFO for once-per-session
  5. transitions (first ``active for <root>``, first ``no project root`` per file) and every
  6. diagnostic event; WARNING for action-required failures (first ``server unavailable`` per
  7. (server_id, binary), every timeout / unexpected error). Dedup uses module-level sets bounded
  8. by the distinct pairs touched in one process, each capped at ``_ANNOUNCE_CAP`` keys: past it the
  9. bucket resets and the first-seen line re-fires once, so per-file keys can't grow for the life of
  10. a gateway process (#62950).
  11. """
  12. from __future__ import annotations
  13. import logging
  14. import os
  15. import threading
  16. from typing import List, Optional, Tuple
  17. # Dedicated logger name so the documented grep recipe survives any
  18. # ``logging.getLogger(__name__)`` rename of internal modules.
  19. event_log = logging.getLogger("hermes.lint.lsp")
  20. _announce_lock = threading.Lock()
  21. _ANNOUNCE_CAP = 512
  22. _announced_active: set = set() # keys: (server_id, workspace_root)
  23. _announced_unavailable: set = set() # keys: (server_id, binary_path_or_name)
  24. _announced_no_root: set = set() # keys: (server_id, file_path)
  25. _announced_skipped: set = set() # keys: (server_id, workspace_root)
  26. _announced_excluded: set = set() # keys: (server_id, workspace_root)
  27. _announced_untrusted: set = set() # keys: (server_id, workspace_root)
  28. _ALL_BUCKETS = (_announced_active, _announced_unavailable, _announced_no_root, _announced_skipped, _announced_excluded,
  29. _announced_untrusted)
  30. def _short_path(file_path: str) -> str:
  31. """Render *file_path* relative to cwd when it's inside it, else absolute (no ``../..`` chains)."""
  32. if not file_path:
  33. return file_path
  34. try:
  35. rel = os.path.relpath(file_path)
  36. except (ValueError, OSError):
  37. # Different drive (ValueError) or the process cwd was removed (OSError from getcwd):
  38. # a log-line shortener must never turn a delivered diagnostic into a swallowed error.
  39. return file_path
  40. return file_path if rel.startswith(".." + os.sep) or rel == ".." else rel
  41. def _emit(server_id: str, level: int, message: str) -> None:
  42. event_log.log(level, "lsp[%s] %s", server_id, message)
  43. def _emit_once(bucket: set, key: tuple, server_id: str, level: int, first: str, repeat: str) -> None:
  44. """Log *first* at *level* the first time *key* is seen, *repeat* at DEBUG thereafter."""
  45. with _announce_lock:
  46. is_first = key not in bucket
  47. if is_first and len(bucket) >= _ANNOUNCE_CAP:
  48. bucket.clear()
  49. bucket.add(key)
  50. _emit(server_id, level if is_first else logging.DEBUG, first if is_first else repeat)
  51. # ---- Public event helpers — call these from the LSP layer ----
  52. def log_clean(server_id: str, file_path: str) -> None:
  53. """No diagnostics emitted for *file_path*. DEBUG."""
  54. _emit(server_id, logging.DEBUG, f"clean ({_short_path(file_path)})")
  55. def log_disabled(server_id: str, file_path: str, reason: str) -> None:
  56. """LSP intentionally skipped for this file (feature off, ext unmapped, ...). DEBUG."""
  57. _emit(server_id, logging.DEBUG, f"skipped: {reason} ({_short_path(file_path)})")
  58. def log_active(server_id: str, workspace_root: str) -> None:
  59. """A client started for (server_id, workspace_root). INFO once per pair, DEBUG thereafter."""
  60. _emit_once(_announced_active, (server_id, workspace_root), server_id, logging.INFO,
  61. f"active for {workspace_root}", f"reused client for {workspace_root}")
  62. def log_diagnostics(server_id: str, file_path: str, count: int) -> None:
  63. """Diagnostics arrived for a file. INFO every time — rare per edit and what users grep for."""
  64. _emit(server_id, logging.INFO, f"{count} diags ({_short_path(file_path)})")
  65. def log_no_project_root(server_id: str, file_path: str) -> None:
  66. """File had no recognised project marker. INFO once per file, DEBUG thereafter."""
  67. msg = f"no project root for {_short_path(file_path)}"
  68. _emit_once(_announced_no_root, (server_id, file_path), server_id, logging.INFO, msg, msg)
  69. def log_server_unavailable(server_id: str, binary_or_pkg: str) -> None:
  70. """Server binary unresolved. WARNING once per (server_id, binary), DEBUG thereafter."""
  71. _emit_once(
  72. _announced_unavailable, (server_id, binary_or_pkg), server_id, logging.WARNING,
  73. f"server unavailable: {binary_or_pkg} not found "
  74. "(install via `hermes lsp install <id>` or set lsp.servers.<id>.command)",
  75. f"server still unavailable: {binary_or_pkg}",
  76. )
  77. def log_timeout(server_id: str, file_path: str, kind: str = "diagnostics") -> None:
  78. """A request to the server timed out. WARNING every time."""
  79. _emit(server_id, logging.WARNING, f"{kind} timed out for {_short_path(file_path)}")
  80. def log_server_error(server_id: str, file_path: str, exc: BaseException) -> None:
  81. """An unexpected exception bubbled out of the LSP layer. WARNING."""
  82. _emit(server_id, logging.WARNING, f"unexpected error for {_short_path(file_path)}: {type(exc).__name__}: {exc}")
  83. def log_spawn_failed(server_id: str, workspace_root: str, exc: BaseException) -> None:
  84. """The LSP server failed to spawn or initialize. WARNING."""
  85. _emit(server_id, logging.WARNING, f"spawn/initialize failed for {workspace_root}: {type(exc).__name__}: {exc}")
  86. def log_skipped_broken(server_id: str, workspace_root: str, file_path: str, retry_in: Optional[float] = None) -> None:
  87. """A request was skipped because ``(server_id, root)`` is marked broken. INFO once per root, then DEBUG:
  88. at default log levels a skipped file and a clean file otherwise look identical (``log_clean`` is DEBUG).
  89. ``retry_in`` (seconds, from ``lsp.broken_retry_seconds``) names when the pair gets another try."""
  90. until = f"retry in {retry_in:.0f}s" if retry_in is not None else "no diagnostics for this root until restart"
  91. _emit_once(_announced_skipped, (server_id, workspace_root), server_id, logging.INFO,
  92. f"skipping {_short_path(file_path)}: {workspace_root} marked broken after an earlier failure ({until})",
  93. f"skipping {_short_path(file_path)}: {workspace_root} marked broken")
  94. def log_root_excluded(server_id: str, workspace_root: str, file_path: str, *, invalid: bool = False) -> None:
  95. """``workspace_root`` matches ``lsp.exclude_roots`` (or the key is malformed and every root is skipped).
  96. INFO once per root — a deliberate gate must still be visible, or an excluded file looks like a clean one —
  97. DEBUG thereafter."""
  98. why = "lsp.exclude_roots is not a list (fix the key)" if invalid else "matches lsp.exclude_roots"
  99. _emit_once(_announced_excluded, (server_id, workspace_root), server_id, logging.INFO,
  100. f"skipping {_short_path(file_path)}: {workspace_root} {why}",
  101. f"skipping {_short_path(file_path)}: {workspace_root} excluded")
  102. def log_untrusted_skipped(server_id: str, workspace_root: str, file_path: str) -> None:
  103. """``server_id`` is not safe in an untrusted workspace and ``workspace_root`` is not trusted.
  104. INFO once per root (a deliberate gate must not look like a clean file), DEBUG thereafter."""
  105. _emit_once(_announced_untrusted, (server_id, workspace_root), server_id, logging.INFO,
  106. f"skipped: untrusted workspace {workspace_root} ({_short_path(file_path)}); "
  107. "add it to lsp.trusted_workspaces to run this server there",
  108. f"skipped: untrusted workspace {workspace_root}")
  109. def log_reaped(keys: list[tuple[str, str]], idle_timeout: float) -> None:
  110. """Idle clients were reaped. INFO, one line per sweep.
  111. Also forgets the ``log_active`` announcement for those keys so a respawn
  112. re-announces at INFO instead of a misleading DEBUG "reused client".
  113. """
  114. with _announce_lock:
  115. _announced_active.difference_update(keys)
  116. summary = ", ".join(f"{sid} ({root})" for sid, root in keys)
  117. _emit("reaper", logging.INFO, f"reaped {len(keys)} idle client(s) after {idle_timeout:.0f}s: {summary}")
  118. def log_released(keys: list[tuple[str, str]], reason: str) -> None:
  119. """Clients were shut down because their workspace went away (worktree released or root deleted).
  120. INFO, one line per event; forgets the ``log_active`` announcement like :func:`log_reaped`."""
  121. with _announce_lock:
  122. _announced_active.difference_update(keys)
  123. summary = ", ".join(f"{sid} ({root})" for sid, root in keys)
  124. _emit("reaper", logging.INFO, f"released {len(keys)} client(s) ({reason}): {summary}")
  125. def reset_announce_caches() -> None:
  126. """Test-only: clear the dedup caches. Production code never calls this."""
  127. with _announce_lock:
  128. for bucket in _ALL_BUCKETS:
  129. bucket.clear()
  130. __all__ = [
  131. "event_log",
  132. "log_active",
  133. "log_clean",
  134. "log_diagnostics",
  135. "log_disabled",
  136. "log_no_project_root",
  137. "log_reaped",
  138. "log_root_excluded",
  139. "log_server_error",
  140. "log_server_unavailable",
  141. "log_skipped_broken",
  142. "log_spawn_failed",
  143. "log_timeout",
  144. "log_untrusted_skipped",
  145. "reset_announce_caches",
  146. ]