shared_metrics_prepared_compaction.py 4.3 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687
  1. """Prepared compaction (``compression.prepare_ahead``): adoption and every way a prepared pass is wasted.
  2. The daily snapshot carries ``compression_prepare_ahead`` (``on``/``off``), read with the agent's own
  3. truthiness, so "active installs with the feature on" needs no join. ``hermes.prepared_compaction.count``
  4. counts each pass and splice outcome from ``agent/prepared_compaction.py`` (and a spliced compaction that
  5. then failed, from ``agent/conversation_compression_telemetry.py``) over closed sets only: the event, the
  6. hook that started the pass, a reason code (never the free-text miss reason), the compression failure
  7. class, and how long a compaction waited on a running pass, bucketed.
  8. The contract imports this module at load time, so it never imports the contract at module level.
  9. """
  10. from __future__ import annotations
  11. from typing import Any
  12. PREPARED_COMPACTION_MARK = PREPARED_COMPACTION_METRIC = "hermes.prepared_compaction.count"
  13. PREPARED_COMPACTION_EVENTS = frozenset({
  14. "auto_disabled", "compaction_failed", "discarded", "internal_error", "pass_cancelled", "pass_completed",
  15. "pass_failed", "pass_started", "skipped_busy", "used",
  16. })
  17. PREPARED_COMPACTION_ORIGINS = frozenset({"none", "tool_batch", "turn_end"})
  18. PREPARED_COMPACTION_REASONS = frozenset({
  19. "agent_released", "aux_fallback_main", "compaction_aborted", "fresh_required", "head_moved", "host_cancelled",
  20. "none", "other_session", "pass_failed_while_waiting", "provider_context", "rewound",
  21. "running_not_fit", "session_boundary", "shape_changed", "superseded", "text_changed",
  22. "transcript_shorter", "wait_timeout",
  23. })
  24. PREPARED_COMPACTION_WAIT_BUCKETS = frozenset({"none", "lt_1s", "1s_to_5s", "5s_to_30s", "30s_to_120s", "gte_120s"})
  25. _WAIT_THRESHOLDS = ((1, "lt_1s"), (5, "1s_to_5s"), (30, "5s_to_30s"), (120, "30s_to_120s"))
  26. # failure_class (the compression vocabulary) is added by the contract, which owns that set.
  27. PREPARED_COMPACTION_DIMENSIONS = {
  28. "event": PREPARED_COMPACTION_EVENTS, "origin": PREPARED_COMPACTION_ORIGINS,
  29. "reason": PREPARED_COMPACTION_REASONS, "wait_bucket": PREPARED_COMPACTION_WAIT_BUCKETS,
  30. }
  31. PREPARED_COMPACTION_SNAPSHOT_DIMENSIONS = {"compression_prepare_ahead": frozenset({"off", "on"})}
  32. def prepare_ahead_state(config: Any) -> str:
  33. """``on`` when the profile config turns ``compression.prepare_ahead`` on, read as the agent reads it."""
  34. from utils import is_truthy_value
  35. compression = config.get("compression") if isinstance(config, dict) else None
  36. value = compression.get("prepare_ahead") if isinstance(compression, dict) else None
  37. return "on" if is_truthy_value(value, default=False) else "off"
  38. def wait_bucket(seconds: Any) -> str:
  39. if isinstance(seconds, bool) or not isinstance(seconds, (int, float)) or seconds < 0:
  40. return "none"
  41. return next((label for limit, label in _WAIT_THRESHOLDS if seconds < limit), "gte_120s")
  42. def _closed(value: Any, allowed: frozenset[str], fallback: str) -> str:
  43. text = str(value or "").strip().lower().replace("-", "_")
  44. return text if text in allowed else fallback
  45. def prepared_compaction_fields(
  46. *, event: Any, origin: Any, reason: Any, failure_class: Any, wait_seconds: Any,
  47. ) -> dict[str, str] | None:
  48. """Closed dimensions for one event; ``None`` for an event outside the set (never recorded)."""
  49. from .shared_metrics_fields import compression_failure_class
  50. name = _closed(event, PREPARED_COMPACTION_EVENTS, "")
  51. if not name:
  52. return None
  53. return {
  54. "event": name,
  55. "failure_class": "none" if failure_class is None else compression_failure_class("failed", failure_class),
  56. "origin": _closed(origin, PREPARED_COMPACTION_ORIGINS, "none"),
  57. "reason": _closed(reason, PREPARED_COMPACTION_REASONS, "none"),
  58. "wait_bucket": wait_bucket(wait_seconds),
  59. }
  60. def record_prepared_compaction(
  61. event: str, *, origin: str | None = None, reason: str | None = None, failure_class: str | None = None,
  62. wait_seconds: float | None = None,
  63. ) -> None:
  64. """Count one prepared-compaction event (no-op unless shared metrics are on; never raises)."""
  65. from .shared_metrics_events import _emit
  66. _emit(
  67. PREPARED_COMPACTION_MARK, prepared_compaction_fields, event=event, origin=origin, reason=reason,
  68. failure_class=failure_class, wait_seconds=wait_seconds,
  69. )