| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277 |
- """Shared-metrics facts the Desktop app reports about itself: area use, friction, first-run steps,
- dislike signals, and one daily report (Bot Mode / Sessions split, button presses per action).
- The renderer dedupes on its side (per-profile state persisted only while collection is on); the
- backend latches again so a second window, a reconnect replay, a backend restart or a cleared
- localStorage cannot inflate a row. Feature use (once per profile, UTC day, area) and the daily report
- (once per profile and usage day, counted in the usage day's period) latch durably in the profile's
- shared-metrics store, in the same transaction as the row; onboarding latches once per (profile, step,
- event) ever in a file; friction and dislike are capped per (profile, UTC day) in this process. Every
- value collapses onto the closed sets in ``shared_metrics_contract``; raw client words are never
- recorded. Every latch is claimed only after the ``enabled()`` gate, so a disabled profile writes nothing.
- """
- from __future__ import annotations
- import logging
- import os
- import platform
- import re
- import shutil
- import threading
- from datetime import date, datetime, timedelta, timezone, UTC
- from typing import Any
- from . import shared_metrics_contract as contract
- from .shared_metrics_events import _emit
- logger = logging.getLogger(__name__)
- # Per-day ceiling for one (kind, detail) friction pair: a toast loop or a janky session still shows
- # up as "a lot", but cannot flood the store.
- FRICTION_DAILY_CAP = 50
- ONBOARDING_LATCH_DIRNAME = "desktop_onboarding"
- # Room for every distinct (action, via) the renderer can send once it collapses unknown ids to `other`.
- DAILY_ACTION_ROWS_MAX = len(contract.DESKTOP_ACTION_IDS) * len(contract.DESKTOP_ACTION_VIAS)
- DAILY_REPORT_STATE_KEY = "desktop_daily_reported"
- # The renderer holds a finished day for at most 7 days; anything older (or in the future) is settled
- # unrecorded, which keeps the durable per-day latch bounded.
- DAILY_REPORT_WINDOW_DAYS = 8
- _DAY = re.compile(r"\d{4}-\d{2}-\d{2}")
- _LATCH_LOCK = threading.Lock()
- # (home, day, key) -> count; pruned to the current day so the process never grows it.
- _daily: dict[tuple[str, str, str], int] = {}
- def _utc_day() -> str:
- return datetime.now(UTC).date().isoformat()
- def _home() -> str:
- from hermes_constants import get_hermes_home
- return str(get_hermes_home())
- def _word(value: Any) -> str:
- return value.strip().lower() if isinstance(value, str) else ""
- def _claim_daily(key: str, *, cap: int = 1, day: str | None = None) -> bool:
- """True while ``key`` has been claimed fewer than ``cap`` times today in this profile."""
- today = _utc_day()
- slot = (_home(), day or today, key)
- with _LATCH_LOCK:
- for stale in [k for k in _daily if k[1] < today and k[1] != slot[1]]:
- del _daily[stale]
- if _daily.get(slot, 0) >= cap:
- return False
- _daily[slot] = _daily.get(slot, 0) + 1
- return True
- def feature_area(area: Any) -> str:
- word = _word(area)
- if word in contract.DESKTOP_FEATURE_AREAS:
- return word
- return "settings_other" if word.startswith("settings_") else "other"
- def friction_pair(kind: Any, detail: Any) -> tuple[str, str] | None:
- """``(kind, detail)`` with detail checked against ITS kind's set; unknown kinds record nothing."""
- kind_word = _word(kind)
- details = contract.DESKTOP_FRICTION_DETAILS.get(kind_word)
- if details is None:
- return None
- detail_word = _word(detail)
- return kind_word, detail_word if detail_word in details else "other"
- def _store_and_resource() -> tuple[Any, dict[str, str]]:
- """The active profile's store and client resource (the subscriber's), for rows that latch
- durably or belong to a past period and so cannot ride the relay's current-day marks."""
- from hermes_cli.version_info import get_version_info
- from .shared_metrics import SharedMetricsStore
- from .shared_metrics_install import detect_client_install_method
- return SharedMetricsStore(), contract.client_resource(
- get_version_info().base_version, os_name=platform.system(), architecture=platform.machine(),
- install_method=detect_client_install_method(),
- )
- def _friction_fields(*, kind: Any, detail: Any) -> dict[str, str] | None:
- pair = friction_pair(kind, detail)
- if pair is None or not _claim_daily(f"friction:{pair[0]}:{pair[1]}", cap=FRICTION_DAILY_CAP):
- return None
- return {"detail": pair[1], "kind": pair[0]}
- def _claim_onboarding(step: str, event: str) -> bool:
- """Once per (step, event) per profile, across processes: an O_EXCL latch file (≤ ~51 of them)."""
- from hermes_constants import get_hermes_home
- directory = get_hermes_home() / "telemetry" / "shared_metrics" / ONBOARDING_LATCH_DIRNAME
- directory.mkdir(parents=True, exist_ok=True)
- try:
- os.close(os.open(directory / f"{step}.{event}", os.O_CREAT | os.O_EXCL | os.O_WRONLY))
- except FileExistsError:
- return False
- return True
- def purge_onboarding_latches() -> None:
- """Collection turned off: drop the per-profile onboarding latches like the renderer drops its copy."""
- from hermes_constants import get_hermes_home
- shutil.rmtree(get_hermes_home() / "telemetry" / "shared_metrics" / ONBOARDING_LATCH_DIRNAME, ignore_errors=True)
- def _onboarding_fields(*, step: Any, event: Any) -> dict[str, str] | None:
- step_word, event_word = _word(step), _word(event)
- if step_word not in contract.DESKTOP_ONBOARDING_STEPS or event_word not in contract.DESKTOP_ONBOARDING_EVENTS:
- return None
- return {"event": event_word, "step": step_word} if _claim_onboarding(step_word, event_word) else None
- def _count(value: Any) -> int:
- return int(value) if isinstance(value, (int, float)) and not isinstance(value, bool) and value >= 0 else 0
- def action_id(action: Any) -> str:
- """Action ids are case-sensitive registry ids (``view.toggleSidebar``): only strip them."""
- word = action.strip() if isinstance(action, str) else ""
- return word if word in contract.DESKTOP_ACTION_IDS else "other"
- def _setting_leaves(config: dict, prefix: str = "") -> dict[str, Any]:
- leaves: dict[str, Any] = {}
- for key, value in config.items():
- path = f"{prefix}.{key}" if prefix else str(key)
- if isinstance(value, dict) and value:
- leaves.update(_setting_leaves(value, path))
- else:
- leaves[path] = value
- return leaves
- def _setting_direction(key: str) -> tuple[str, str]:
- """``(setting, direction)`` for a config key the Desktop settings page just saved: the key only if
- it is a DEFAULT_CONFIG leaf (the settings schema), the direction from comparing the saved value to
- the default here in the backend, so the value never leaves this process."""
- from hermes_cli.config import DEFAULT_CONFIG, load_config
- defaults = _setting_leaves(DEFAULT_CONFIG)
- if key not in defaults or len(key) > contract.DESKTOP_SETTING_KEY_MAX_LENGTH:
- return "other", "none"
- current: Any = load_config()
- for part in key.split("."):
- current = current.get(part) if isinstance(current, dict) else None
- return key, "to_default" if current == defaults[key] else "away_from_default"
- def _dislike_fields(*, signal: Any, target: Any, setting: Any) -> dict[str, str] | None:
- signal_word = _word(signal)
- targets = contract.DESKTOP_DISLIKE_TARGETS.get(signal_word)
- if targets is None:
- return None
- if signal_word == "setting_off_default":
- key = setting.strip() if isinstance(setting, str) else ""
- setting_word, direction = _setting_direction(key)
- target_word = "setting"
- else:
- raw = target.strip() if isinstance(target, str) else ""
- target_word = raw if signal_word == "rage_click" and raw in targets else _word(raw)
- target_word = target_word if target_word in targets else "other"
- setting_word, direction = "none", "none"
- if not _claim_daily(f"dislike:{signal_word}", cap=FRICTION_DAILY_CAP):
- return None
- return {"direction": direction, "setting": setting_word, "signal": signal_word, "target": target_word}
- def _mode_rows(modes: Any, bot_count: Any) -> list[tuple[str, dict[str, str]]]:
- rows: dict[str, tuple[str, dict[str, str]]] = {}
- for entry in modes if isinstance(modes, list) else []:
- mode = _word(entry.get("mode")) if isinstance(entry, dict) else ""
- active_ms, messages = (_count(entry.get("active_ms")), _count(entry.get("messages_sent"))) if mode else (0, 0)
- # Only modes actually used that day get a row.
- if mode not in contract.DESKTOP_MODES or mode in rows or not (active_ms or messages):
- continue
- rows[mode] = (contract.DESKTOP_MODE_USE_MARK, {
- "active_minutes_bucket": contract.desktop_active_minutes_bucket(active_ms),
- "bot_count_bucket": contract.size_bucket(_count(bot_count)),
- "messages_sent_bucket": contract.size_bucket(messages),
- "mode": mode,
- })
- return list(rows.values())
- def _action_rows(actions: Any) -> list[tuple[str, dict[str, str]]]:
- totals: dict[tuple[str, str], int] = {}
- for entry in (actions if isinstance(actions, list) else [])[:DAILY_ACTION_ROWS_MAX]:
- if not isinstance(entry, dict) or _word(entry.get("via")) not in contract.DESKTOP_ACTION_VIAS:
- continue
- key = (action_id(entry.get("action")), _word(entry.get("via")))
- totals[key] = totals.get(key, 0) + _count(entry.get("count"))
- return [
- (contract.DESKTOP_ACTION_USE_MARK, {"action": action, "count_bucket": contract.size_bucket(count), "via": via})
- for (action, via), count in sorted(totals.items()) if count
- ]
- def _daily_rollup(usage_day: str, oldest: str, marks: list[tuple[str, dict[str, str]]], resource: dict[str, str]):
- """``update_rollup_state`` step: the usage day's rows, unless that day was already reported."""
- def update(state: dict[str, Any] | None) -> tuple[dict[str, Any], list[tuple[str, dict, dict, str]]]:
- days = [d for d in (state or {}).get("days", []) if isinstance(d, str) and d >= oldest]
- if usage_day in days:
- return {"days": days}, []
- return {"days": sorted([*days, usage_day])}, [(mark, data, resource, usage_day) for mark, data in marks]
- return update
- def record_desktop_daily(*, day: Any, modes: Any, actions: Any, bot_count: Any) -> bool:
- """Record one finished Desktop day, in that day's period: a mode_use row per mode used (with the
- bot count) and an action_use row per (action, via). True once the day is settled (saved, already
- reported, empty or out of range) so the client drops its copy; False keeps it for the next attach,
- including when this profile's collection is off (the client's own gate decides what it keeps)."""
- try:
- from .relay_shared_metrics import enabled
- if not enabled():
- return False
- today = _utc_day()
- oldest = (date.fromisoformat(today) - timedelta(days=DAILY_REPORT_WINDOW_DAYS)).isoformat()
- usage_day = day if isinstance(day, str) and _DAY.fullmatch(day) and oldest <= day <= today else None
- marks = _mode_rows(modes, bot_count) + _action_rows(actions) if usage_day else []
- if marks:
- store, resource = _store_and_resource()
- store.update_rollup_state(DAILY_REPORT_STATE_KEY, _daily_rollup(usage_day, oldest, marks, resource))
- return True
- except Exception:
- logger.debug("Desktop daily report not recorded", exc_info=True)
- return False
- def record_desktop_feature_use(*, area: Any) -> None:
- """Once per (profile, UTC day, area), latched in the store with the row (never raises)."""
- try:
- from .relay_shared_metrics import enabled
- if enabled():
- store, resource = _store_and_resource()
- store.record_counter_once_per_day(contract.DESKTOP_FEATURE_USE_METRIC, {"area": feature_area(area)}, resource)
- except Exception:
- logger.debug("Desktop feature use not recorded", exc_info=True)
- def record_desktop_friction(*, kind: Any, detail: Any) -> None:
- _emit(contract.DESKTOP_FRICTION_MARK, _friction_fields, kind=kind, detail=detail)
- def record_desktop_onboarding(*, step: Any, event: Any) -> None:
- _emit(contract.DESKTOP_ONBOARDING_MARK, _onboarding_fields, step=step, event=event)
- def record_desktop_dislike(*, signal: Any, target: Any, setting: Any = None) -> None:
- _emit(contract.DESKTOP_DISLIKE_MARK, _dislike_fields, signal=signal, target=target, setting=setting)
|