shared_metrics_startup.py 6.2 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152
  1. """Startup / attach latency: one bucketed row per process start and surface.
  2. In-process surfaces (classic CLI, messaging gateway, ``hermes serve``) measure from the OS process
  3. creation time, the earliest timestamp available (it includes interpreter start and imports), to the
  4. moment they are ready. The Ink TUI and the Desktop app measure on their own side and report through
  5. the ``shared_metrics.startup_latency`` RPC. Recording goes through the shared ``_emit`` gate, so a
  6. profile without shared metrics enabled records nothing.
  7. """
  8. from __future__ import annotations
  9. import contextvars
  10. import logging
  11. import os
  12. import threading
  13. import time
  14. from typing import Any
  15. from . import shared_metrics_contract as contract
  16. from .shared_metrics_contract import _bucket, _non_negative_number
  17. logger = logging.getLogger(__name__)
  18. _THRESHOLDS_MS = (
  19. (500, "lt_500ms"), (1_000, "500ms_to_1s"), (2_000, "1s_to_2s"), (5_000, "2s_to_5s"), (10_000, "5s_to_10s"),
  20. )
  21. # (pid, surface, client launch id): a forked child re-arms, a surface in this process counts once,
  22. # and an RPC-reporting client counts once per launch (a Desktop reconnect re-sends the same launch).
  23. _recorded: set[tuple[int, str, str]] = set()
  24. _lock = threading.Lock()
  25. # A local client minting a fresh launch id per call must not grow this set without bound.
  26. _MAX_RECORDED = 1024
  27. _LAUNCH_ID_MAX_LEN = 64
  28. # ``os.execvp`` keeps the PID, so a relaunched process (``sessions browse`` -> resume) would count
  29. # the picker time as startup; relaunch() stamps its PID here right before the exec.
  30. RELAUNCHED_PID_ENV = "HERMES_RELAUNCHED_PID"
  31. def latency_bucket(elapsed_ms: Any) -> str | None:
  32. value = _non_negative_number(elapsed_ms)
  33. return None if value is None else _bucket(value, _THRESHOLDS_MS, "gte_10s")
  34. def startup_latency_fields(*, surface: Any, elapsed_ms: Any) -> dict[str, str] | None:
  35. bucket = latency_bucket(elapsed_ms)
  36. if surface not in contract.STARTUP_SURFACES or bucket is None:
  37. return None
  38. return {"latency_bucket": bucket, "surface": surface}
  39. def record_startup_latency(*, surface: str, elapsed_ms: Any) -> None:
  40. """Record one measured startup (no-op unless shared metrics are on; never raises)."""
  41. from .shared_metrics_events import _emit
  42. _emit(contract.STARTUP_LATENCY_MARK, startup_latency_fields, surface=surface, elapsed_ms=elapsed_ms)
  43. def process_started_at() -> float | None:
  44. """Epoch seconds at which the OS created this process, or ``None`` when unreadable."""
  45. try:
  46. import psutil
  47. return float(psutil.Process(os.getpid()).create_time())
  48. except Exception:
  49. return None
  50. def mark_in_place_relaunch() -> None:
  51. """Called right before an in-place ``exec``: the new program inherits this PID and env."""
  52. os.environ[RELAUNCHED_PID_ENV] = str(os.getpid())
  53. def _relaunched_in_place() -> bool:
  54. # A child spawned later inherits the env but has its own PID, so it still counts.
  55. return os.environ.get(RELAUNCHED_PID_ENV) == str(os.getpid())
  56. def _claim(surface: str, launch_id: str = "") -> bool:
  57. key = (os.getpid(), surface, launch_id)
  58. with _lock:
  59. if key in _recorded or len(_recorded) >= _MAX_RECORDED:
  60. return False
  61. _recorded.add(key)
  62. return True
  63. def _collection_enabled() -> bool:
  64. from .relay_shared_metrics import enabled
  65. return enabled()
  66. def _record_since_process_start(surface: str, ready_at: float) -> None:
  67. started = process_started_at()
  68. if started is not None:
  69. record_startup_latency(surface=surface, elapsed_ms=max(0.0, ready_at - started) * 1000)
  70. def record_process_ready(surface: str, *, background: bool = False) -> None:
  71. """``surface`` became ready now: record process-start -> now once per process.
  72. ``background`` hands the (possibly cold, ~seconds) metrics runtime start to a daemon thread
  73. under the caller's contextvars (profile binding), so an event loop never waits on it; the
  74. ready time is taken before the hand-off.
  75. """
  76. ready_at = time.time()
  77. try:
  78. # Claim before the gate so a later opt-in never records a stale "startup" mid-session.
  79. if _relaunched_in_place() or not _claim(surface) or not _collection_enabled():
  80. return
  81. if not background:
  82. _record_since_process_start(surface, ready_at)
  83. return
  84. context = contextvars.copy_context()
  85. threading.Thread(
  86. target=context.run, args=(_record_since_process_start, surface, ready_at),
  87. name="hermes-startup-latency", daemon=True,
  88. ).start()
  89. except Exception:
  90. logger.debug("Startup latency for %s not recorded", surface, exc_info=True)
  91. def cli_prompt_ready_handler():
  92. """A prompt_toolkit ``after_render`` handler that records the first rendered prompt once."""
  93. def _on_render(_app: Any) -> None:
  94. record_process_ready("cli", background=True)
  95. return _on_render
  96. def record_cli_one_shot_ready() -> None:
  97. """A ``-q`` run is ready to dispatch its query. Kanban workers are dispatched processes, not a
  98. user waiting on a prompt, so they stay out of the CLI startup distribution."""
  99. if not os.environ.get("HERMES_KANBAN_TASK"):
  100. record_process_ready("cli")
  101. def _launch_key(launch_id: Any) -> str:
  102. """The client's per-launch id, only ever a local latch key (never recorded). Older clients send
  103. none and latch on their side; they count once per backend process and surface."""
  104. return launch_id if isinstance(launch_id, str) and len(launch_id) <= _LAUNCH_ID_MAX_LEN else ""
  105. def record_rpc_startup_latency(*, client_surface: Any, elapsed_ms: Any, launch_id: Any = None) -> None:
  106. """The TUI / Desktop client's own launch -> ready measurement, once per (surface, client launch)
  107. in this backend process. ``client_surface`` is the client's declared surface or the backend's
  108. detection (``desktop``/``tui``); anything else records nothing."""
  109. surface = {"desktop": "desktop_attach", "desktop_attach": "desktop_attach", "tui": "tui"}.get(client_surface)
  110. # Only a usable measurement spends the launch's claim.
  111. if surface is not None and latency_bucket(elapsed_ms) is not None and _claim(surface, _launch_key(launch_id)):
  112. record_startup_latency(surface=surface, elapsed_ms=elapsed_ms)