shared_metrics_desktop.py 12 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277
  1. """Shared-metrics facts the Desktop app reports about itself: area use, friction, first-run steps,
  2. dislike signals, and one daily report (Bot Mode / Sessions split, button presses per action).
  3. The renderer dedupes on its side (per-profile state persisted only while collection is on); the
  4. backend latches again so a second window, a reconnect replay, a backend restart or a cleared
  5. localStorage cannot inflate a row. Feature use (once per profile, UTC day, area) and the daily report
  6. (once per profile and usage day, counted in the usage day's period) latch durably in the profile's
  7. shared-metrics store, in the same transaction as the row; onboarding latches once per (profile, step,
  8. event) ever in a file; friction and dislike are capped per (profile, UTC day) in this process. Every
  9. value collapses onto the closed sets in ``shared_metrics_contract``; raw client words are never
  10. recorded. Every latch is claimed only after the ``enabled()`` gate, so a disabled profile writes nothing.
  11. """
  12. from __future__ import annotations
  13. import logging
  14. import os
  15. import platform
  16. import re
  17. import shutil
  18. import threading
  19. from datetime import date, datetime, timedelta, timezone, UTC
  20. from typing import Any
  21. from . import shared_metrics_contract as contract
  22. from .shared_metrics_events import _emit
  23. logger = logging.getLogger(__name__)
  24. # Per-day ceiling for one (kind, detail) friction pair: a toast loop or a janky session still shows
  25. # up as "a lot", but cannot flood the store.
  26. FRICTION_DAILY_CAP = 50
  27. ONBOARDING_LATCH_DIRNAME = "desktop_onboarding"
  28. # Room for every distinct (action, via) the renderer can send once it collapses unknown ids to `other`.
  29. DAILY_ACTION_ROWS_MAX = len(contract.DESKTOP_ACTION_IDS) * len(contract.DESKTOP_ACTION_VIAS)
  30. DAILY_REPORT_STATE_KEY = "desktop_daily_reported"
  31. # The renderer holds a finished day for at most 7 days; anything older (or in the future) is settled
  32. # unrecorded, which keeps the durable per-day latch bounded.
  33. DAILY_REPORT_WINDOW_DAYS = 8
  34. _DAY = re.compile(r"\d{4}-\d{2}-\d{2}")
  35. _LATCH_LOCK = threading.Lock()
  36. # (home, day, key) -> count; pruned to the current day so the process never grows it.
  37. _daily: dict[tuple[str, str, str], int] = {}
  38. def _utc_day() -> str:
  39. return datetime.now(UTC).date().isoformat()
  40. def _home() -> str:
  41. from hermes_constants import get_hermes_home
  42. return str(get_hermes_home())
  43. def _word(value: Any) -> str:
  44. return value.strip().lower() if isinstance(value, str) else ""
  45. def _claim_daily(key: str, *, cap: int = 1, day: str | None = None) -> bool:
  46. """True while ``key`` has been claimed fewer than ``cap`` times today in this profile."""
  47. today = _utc_day()
  48. slot = (_home(), day or today, key)
  49. with _LATCH_LOCK:
  50. for stale in [k for k in _daily if k[1] < today and k[1] != slot[1]]:
  51. del _daily[stale]
  52. if _daily.get(slot, 0) >= cap:
  53. return False
  54. _daily[slot] = _daily.get(slot, 0) + 1
  55. return True
  56. def feature_area(area: Any) -> str:
  57. word = _word(area)
  58. if word in contract.DESKTOP_FEATURE_AREAS:
  59. return word
  60. return "settings_other" if word.startswith("settings_") else "other"
  61. def friction_pair(kind: Any, detail: Any) -> tuple[str, str] | None:
  62. """``(kind, detail)`` with detail checked against ITS kind's set; unknown kinds record nothing."""
  63. kind_word = _word(kind)
  64. details = contract.DESKTOP_FRICTION_DETAILS.get(kind_word)
  65. if details is None:
  66. return None
  67. detail_word = _word(detail)
  68. return kind_word, detail_word if detail_word in details else "other"
  69. def _store_and_resource() -> tuple[Any, dict[str, str]]:
  70. """The active profile's store and client resource (the subscriber's), for rows that latch
  71. durably or belong to a past period and so cannot ride the relay's current-day marks."""
  72. from hermes_cli.version_info import get_version_info
  73. from .shared_metrics import SharedMetricsStore
  74. from .shared_metrics_install import detect_client_install_method
  75. return SharedMetricsStore(), contract.client_resource(
  76. get_version_info().base_version, os_name=platform.system(), architecture=platform.machine(),
  77. install_method=detect_client_install_method(),
  78. )
  79. def _friction_fields(*, kind: Any, detail: Any) -> dict[str, str] | None:
  80. pair = friction_pair(kind, detail)
  81. if pair is None or not _claim_daily(f"friction:{pair[0]}:{pair[1]}", cap=FRICTION_DAILY_CAP):
  82. return None
  83. return {"detail": pair[1], "kind": pair[0]}
  84. def _claim_onboarding(step: str, event: str) -> bool:
  85. """Once per (step, event) per profile, across processes: an O_EXCL latch file (≤ ~51 of them)."""
  86. from hermes_constants import get_hermes_home
  87. directory = get_hermes_home() / "telemetry" / "shared_metrics" / ONBOARDING_LATCH_DIRNAME
  88. directory.mkdir(parents=True, exist_ok=True)
  89. try:
  90. os.close(os.open(directory / f"{step}.{event}", os.O_CREAT | os.O_EXCL | os.O_WRONLY))
  91. except FileExistsError:
  92. return False
  93. return True
  94. def purge_onboarding_latches() -> None:
  95. """Collection turned off: drop the per-profile onboarding latches like the renderer drops its copy."""
  96. from hermes_constants import get_hermes_home
  97. shutil.rmtree(get_hermes_home() / "telemetry" / "shared_metrics" / ONBOARDING_LATCH_DIRNAME, ignore_errors=True)
  98. def _onboarding_fields(*, step: Any, event: Any) -> dict[str, str] | None:
  99. step_word, event_word = _word(step), _word(event)
  100. if step_word not in contract.DESKTOP_ONBOARDING_STEPS or event_word not in contract.DESKTOP_ONBOARDING_EVENTS:
  101. return None
  102. return {"event": event_word, "step": step_word} if _claim_onboarding(step_word, event_word) else None
  103. def _count(value: Any) -> int:
  104. return int(value) if isinstance(value, (int, float)) and not isinstance(value, bool) and value >= 0 else 0
  105. def action_id(action: Any) -> str:
  106. """Action ids are case-sensitive registry ids (``view.toggleSidebar``): only strip them."""
  107. word = action.strip() if isinstance(action, str) else ""
  108. return word if word in contract.DESKTOP_ACTION_IDS else "other"
  109. def _setting_leaves(config: dict, prefix: str = "") -> dict[str, Any]:
  110. leaves: dict[str, Any] = {}
  111. for key, value in config.items():
  112. path = f"{prefix}.{key}" if prefix else str(key)
  113. if isinstance(value, dict) and value:
  114. leaves.update(_setting_leaves(value, path))
  115. else:
  116. leaves[path] = value
  117. return leaves
  118. def _setting_direction(key: str) -> tuple[str, str]:
  119. """``(setting, direction)`` for a config key the Desktop settings page just saved: the key only if
  120. it is a DEFAULT_CONFIG leaf (the settings schema), the direction from comparing the saved value to
  121. the default here in the backend, so the value never leaves this process."""
  122. from hermes_cli.config import DEFAULT_CONFIG, load_config
  123. defaults = _setting_leaves(DEFAULT_CONFIG)
  124. if key not in defaults or len(key) > contract.DESKTOP_SETTING_KEY_MAX_LENGTH:
  125. return "other", "none"
  126. current: Any = load_config()
  127. for part in key.split("."):
  128. current = current.get(part) if isinstance(current, dict) else None
  129. return key, "to_default" if current == defaults[key] else "away_from_default"
  130. def _dislike_fields(*, signal: Any, target: Any, setting: Any) -> dict[str, str] | None:
  131. signal_word = _word(signal)
  132. targets = contract.DESKTOP_DISLIKE_TARGETS.get(signal_word)
  133. if targets is None:
  134. return None
  135. if signal_word == "setting_off_default":
  136. key = setting.strip() if isinstance(setting, str) else ""
  137. setting_word, direction = _setting_direction(key)
  138. target_word = "setting"
  139. else:
  140. raw = target.strip() if isinstance(target, str) else ""
  141. target_word = raw if signal_word == "rage_click" and raw in targets else _word(raw)
  142. target_word = target_word if target_word in targets else "other"
  143. setting_word, direction = "none", "none"
  144. if not _claim_daily(f"dislike:{signal_word}", cap=FRICTION_DAILY_CAP):
  145. return None
  146. return {"direction": direction, "setting": setting_word, "signal": signal_word, "target": target_word}
  147. def _mode_rows(modes: Any, bot_count: Any) -> list[tuple[str, dict[str, str]]]:
  148. rows: dict[str, tuple[str, dict[str, str]]] = {}
  149. for entry in modes if isinstance(modes, list) else []:
  150. mode = _word(entry.get("mode")) if isinstance(entry, dict) else ""
  151. active_ms, messages = (_count(entry.get("active_ms")), _count(entry.get("messages_sent"))) if mode else (0, 0)
  152. # Only modes actually used that day get a row.
  153. if mode not in contract.DESKTOP_MODES or mode in rows or not (active_ms or messages):
  154. continue
  155. rows[mode] = (contract.DESKTOP_MODE_USE_MARK, {
  156. "active_minutes_bucket": contract.desktop_active_minutes_bucket(active_ms),
  157. "bot_count_bucket": contract.size_bucket(_count(bot_count)),
  158. "messages_sent_bucket": contract.size_bucket(messages),
  159. "mode": mode,
  160. })
  161. return list(rows.values())
  162. def _action_rows(actions: Any) -> list[tuple[str, dict[str, str]]]:
  163. totals: dict[tuple[str, str], int] = {}
  164. for entry in (actions if isinstance(actions, list) else [])[:DAILY_ACTION_ROWS_MAX]:
  165. if not isinstance(entry, dict) or _word(entry.get("via")) not in contract.DESKTOP_ACTION_VIAS:
  166. continue
  167. key = (action_id(entry.get("action")), _word(entry.get("via")))
  168. totals[key] = totals.get(key, 0) + _count(entry.get("count"))
  169. return [
  170. (contract.DESKTOP_ACTION_USE_MARK, {"action": action, "count_bucket": contract.size_bucket(count), "via": via})
  171. for (action, via), count in sorted(totals.items()) if count
  172. ]
  173. def _daily_rollup(usage_day: str, oldest: str, marks: list[tuple[str, dict[str, str]]], resource: dict[str, str]):
  174. """``update_rollup_state`` step: the usage day's rows, unless that day was already reported."""
  175. def update(state: dict[str, Any] | None) -> tuple[dict[str, Any], list[tuple[str, dict, dict, str]]]:
  176. days = [d for d in (state or {}).get("days", []) if isinstance(d, str) and d >= oldest]
  177. if usage_day in days:
  178. return {"days": days}, []
  179. return {"days": sorted([*days, usage_day])}, [(mark, data, resource, usage_day) for mark, data in marks]
  180. return update
  181. def record_desktop_daily(*, day: Any, modes: Any, actions: Any, bot_count: Any) -> bool:
  182. """Record one finished Desktop day, in that day's period: a mode_use row per mode used (with the
  183. bot count) and an action_use row per (action, via). True once the day is settled (saved, already
  184. reported, empty or out of range) so the client drops its copy; False keeps it for the next attach,
  185. including when this profile's collection is off (the client's own gate decides what it keeps)."""
  186. try:
  187. from .relay_shared_metrics import enabled
  188. if not enabled():
  189. return False
  190. today = _utc_day()
  191. oldest = (date.fromisoformat(today) - timedelta(days=DAILY_REPORT_WINDOW_DAYS)).isoformat()
  192. usage_day = day if isinstance(day, str) and _DAY.fullmatch(day) and oldest <= day <= today else None
  193. marks = _mode_rows(modes, bot_count) + _action_rows(actions) if usage_day else []
  194. if marks:
  195. store, resource = _store_and_resource()
  196. store.update_rollup_state(DAILY_REPORT_STATE_KEY, _daily_rollup(usage_day, oldest, marks, resource))
  197. return True
  198. except Exception:
  199. logger.debug("Desktop daily report not recorded", exc_info=True)
  200. return False
  201. def record_desktop_feature_use(*, area: Any) -> None:
  202. """Once per (profile, UTC day, area), latched in the store with the row (never raises)."""
  203. try:
  204. from .relay_shared_metrics import enabled
  205. if enabled():
  206. store, resource = _store_and_resource()
  207. store.record_counter_once_per_day(contract.DESKTOP_FEATURE_USE_METRIC, {"area": feature_area(area)}, resource)
  208. except Exception:
  209. logger.debug("Desktop feature use not recorded", exc_info=True)
  210. def record_desktop_friction(*, kind: Any, detail: Any) -> None:
  211. _emit(contract.DESKTOP_FRICTION_MARK, _friction_fields, kind=kind, detail=detail)
  212. def record_desktop_onboarding(*, step: Any, event: Any) -> None:
  213. _emit(contract.DESKTOP_ONBOARDING_MARK, _onboarding_fields, step=step, event=event)
  214. def record_desktop_dislike(*, signal: Any, target: Any, setting: Any = None) -> None:
  215. _emit(contract.DESKTOP_DISLIKE_MARK, _dislike_fields, signal=signal, target=target, setting=setting)