| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190 |
- """Relay subscriber for the persisted Hermes shared-metrics slice."""
- from __future__ import annotations
- import logging
- import platform
- import threading
- from typing import Any
- from agent.relay_runtime import RUNTIME_INSTANCE_KEY
- from hermes_constants import get_hermes_home
- from . import shared_metrics_engagement as engagement
- from . import shared_metrics_signals as signals
- from .shared_metrics import SharedMetricsStore
- from .shared_metrics_fields import milestones_for
- from .shared_metrics_install import detect_client_install_method
- from .shared_metrics_contract import (
- CLIENT_ACTIVE_METRIC,
- COMMIT_TICKET_KEY,
- FEATURE_DISABLED_METRIC,
- FEATURE_USED_MARK,
- INSTALL_SNAPSHOT_METRIC,
- MODEL_ROUTE_METRIC,
- TOOL_CALL_METRIC,
- TOOL_LATENCY_METRIC,
- TOOL_USAGE_METRIC,
- client_active_counter,
- client_resource,
- decision_counter,
- install_snapshot_counter,
- model_call_dimensions,
- model_token_counters,
- skill_counter,
- task_counter,
- task_duration_counter,
- tool_approval_counter,
- tool_call_dimensions,
- tool_latency_dimensions,
- tool_usage_dimensions,
- )
- logger = logging.getLogger(__name__)
- # Contract projections; each yields (metric_name, dimensions) or None. One tool end event feeds
- # the category, per-tool and latency counters (one task end event the task and duration counters),
- # so every match is recorded.
- _COUNTERS = (
- client_active_counter,
- install_snapshot_counter,
- lambda event: _named(MODEL_ROUTE_METRIC, model_call_dimensions(event)),
- lambda event: _named(TOOL_CALL_METRIC, tool_call_dimensions(event)),
- lambda event: _named(TOOL_USAGE_METRIC, tool_usage_dimensions(event)),
- lambda event: _named(TOOL_LATENCY_METRIC, tool_latency_dimensions(event)),
- task_counter,
- task_duration_counter,
- tool_approval_counter,
- skill_counter,
- decision_counter,
- signals.feature_used_counter,
- )
- def _named(metric_name: str, dimensions: dict | None) -> tuple[str, dict] | None:
- return None if dimensions is None else (metric_name, dimensions)
- class SharedMetricsSubscriber:
- """Persist validated Hermes counters from Relay lifecycle events."""
- def __init__(
- self,
- store: SharedMetricsStore,
- hermes_version: str,
- *,
- runtime_id: str | None = None,
- ) -> None:
- self.store = store
- self._client_resource = client_resource(
- hermes_version,
- os_name=platform.system(),
- architecture=platform.machine(),
- install_method=detect_client_install_method(),
- )
- self._runtime_id = runtime_id
- self._active = True
- self._lock = threading.RLock()
- self._milestones_done: set[str] = set(store.recorded_milestones())
- self._features_done: set[str] = set(store.recorded_features())
- self._saved_tickets: dict[str, int] = {}
- # Events arrive on the Relay thread, which carries no profile binding.
- self._hermes_home = get_hermes_home()
- def deactivate(self) -> None:
- """Stop accepting events before telemetry is disabled or torn down."""
- with self._lock:
- self._active = False
- @staticmethod
- def _classify(event: Any) -> list[tuple[str, dict, int]]:
- """Return every ``(metric_name, dimensions, amount)`` the event satisfies."""
- counted = [(*m, 1) for m in (project(event) for project in _COUNTERS) if m is not None]
- return counted + model_token_counters(event)
- def _record_milestones(self, metric_name: str, dimensions: dict) -> None:
- """Latch every install milestone this counter reaches (each once per install, ever)."""
- reached = [m for m in milestones_for(metric_name, dimensions) if m not in self._milestones_done]
- if not reached:
- return
- from .shared_metrics_snapshot import install_age_bucket
- age = install_age_bucket(self._hermes_home)
- for milestone in reached:
- self.store.record_milestone(milestone, age, self._client_resource)
- self._milestones_done.add(milestone)
- def _record_engagement(self, event: Any, classified: list[tuple[str, dict, int]]) -> None:
- """Fold a turn start/end or an attended turn's model into the local daily engagement rollup."""
- surface, route = engagement.interaction_surface(classified), engagement.turn_route(event)
- if surface is None and route is None:
- return
- with self._lock:
- if not self._active:
- return
- try:
- engagement.record(self.store, self._client_resource, surface=surface, route=route)
- except Exception:
- logger.warning("Unable to update the Hermes engagement rollup", exc_info=True)
- def _persist(self, metric_name: str, dimensions: dict, amount: int) -> None:
- store, resource = self.store, self._client_resource
- special = {
- FEATURE_USED_MARK: lambda: None, # a first-use fact, not a counter row
- FEATURE_DISABLED_METRIC: lambda: store.record_counter_once_per_day(metric_name, dimensions, resource),
- CLIENT_ACTIVE_METRIC: lambda: store.record_client_active(resource),
- INSTALL_SNAPSHOT_METRIC: lambda: store.record_install_snapshot(dimensions, resource),
- }.get(metric_name)
- if special is not None:
- special()
- else:
- store.record_counter(metric_name, dimensions, resource, amount)
- def _record_features(self, metric_name: str, dimensions: dict) -> None:
- """Latch each feature's first real use (once per install, with the owning profile's age)."""
- reached = [f for f in signals.features_for(metric_name, dimensions) if f not in self._features_done]
- if not reached:
- return
- age = signals.days_since_install_bucket(self._hermes_home)
- for feature in reached:
- try:
- self.store.record_feature_adoption(feature, age, self._client_resource)
- except Exception: # the counter row is saved; a later use retries the latch
- logger.debug("Feature adoption not latched: %s", feature, exc_info=True)
- continue
- self._features_done.add(feature)
- def take_saved(self, ticket: str) -> int:
- """How many events carrying ``ticket`` settled without a store error (and forget the ticket)."""
- with self._lock:
- return self._saved_tickets.pop(ticket, 0)
- def __call__(self, event: Any) -> None:
- metadata = getattr(event, "metadata", None)
- if self._runtime_id is not None:
- if (
- not isinstance(metadata, dict)
- or metadata.get(RUNTIME_INSTANCE_KEY) != self._runtime_id
- ):
- return
- ticket = metadata.get(COMMIT_TICKET_KEY) if isinstance(metadata, dict) else None
- saved = True # a row the contract rejects is settled too: no retry can change that
- classified = self._classify(event)
- self._record_engagement(event, classified)
- for metric_name, dimensions, amount in classified:
- with self._lock:
- if not self._active:
- return
- try:
- self._persist(metric_name, dimensions, amount)
- self._record_milestones(metric_name, dimensions)
- self._record_features(metric_name, dimensions)
- except Exception:
- saved = False
- logger.warning(
- "Unable to persist the Hermes shared metric: %s", metric_name, exc_info=True
- )
- if ticket and saved:
- with self._lock:
- if self._active:
- self._saved_tickets[ticket] = self._saved_tickets.get(ticket, 0) + 1
|