| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687 |
- """Prepared compaction (``compression.prepare_ahead``): adoption and every way a prepared pass is wasted.
- The daily snapshot carries ``compression_prepare_ahead`` (``on``/``off``), read with the agent's own
- truthiness, so "active installs with the feature on" needs no join. ``hermes.prepared_compaction.count``
- counts each pass and splice outcome from ``agent/prepared_compaction.py`` (and a spliced compaction that
- then failed, from ``agent/conversation_compression_telemetry.py``) over closed sets only: the event, the
- hook that started the pass, a reason code (never the free-text miss reason), the compression failure
- class, and how long a compaction waited on a running pass, bucketed.
- The contract imports this module at load time, so it never imports the contract at module level.
- """
- from __future__ import annotations
- from typing import Any
- PREPARED_COMPACTION_MARK = PREPARED_COMPACTION_METRIC = "hermes.prepared_compaction.count"
- PREPARED_COMPACTION_EVENTS = frozenset({
- "auto_disabled", "compaction_failed", "discarded", "internal_error", "pass_cancelled", "pass_completed",
- "pass_failed", "pass_started", "skipped_busy", "used",
- })
- PREPARED_COMPACTION_ORIGINS = frozenset({"none", "tool_batch", "turn_end"})
- PREPARED_COMPACTION_REASONS = frozenset({
- "agent_released", "aux_fallback_main", "compaction_aborted", "fresh_required", "head_moved", "host_cancelled",
- "none", "other_session", "pass_failed_while_waiting", "provider_context", "rewound",
- "running_not_fit", "session_boundary", "shape_changed", "superseded", "text_changed",
- "transcript_shorter", "wait_timeout",
- })
- PREPARED_COMPACTION_WAIT_BUCKETS = frozenset({"none", "lt_1s", "1s_to_5s", "5s_to_30s", "30s_to_120s", "gte_120s"})
- _WAIT_THRESHOLDS = ((1, "lt_1s"), (5, "1s_to_5s"), (30, "5s_to_30s"), (120, "30s_to_120s"))
- # failure_class (the compression vocabulary) is added by the contract, which owns that set.
- PREPARED_COMPACTION_DIMENSIONS = {
- "event": PREPARED_COMPACTION_EVENTS, "origin": PREPARED_COMPACTION_ORIGINS,
- "reason": PREPARED_COMPACTION_REASONS, "wait_bucket": PREPARED_COMPACTION_WAIT_BUCKETS,
- }
- PREPARED_COMPACTION_SNAPSHOT_DIMENSIONS = {"compression_prepare_ahead": frozenset({"off", "on"})}
- def prepare_ahead_state(config: Any) -> str:
- """``on`` when the profile config turns ``compression.prepare_ahead`` on, read as the agent reads it."""
- from utils import is_truthy_value
- compression = config.get("compression") if isinstance(config, dict) else None
- value = compression.get("prepare_ahead") if isinstance(compression, dict) else None
- return "on" if is_truthy_value(value, default=False) else "off"
- def wait_bucket(seconds: Any) -> str:
- if isinstance(seconds, bool) or not isinstance(seconds, (int, float)) or seconds < 0:
- return "none"
- return next((label for limit, label in _WAIT_THRESHOLDS if seconds < limit), "gte_120s")
- def _closed(value: Any, allowed: frozenset[str], fallback: str) -> str:
- text = str(value or "").strip().lower().replace("-", "_")
- return text if text in allowed else fallback
- def prepared_compaction_fields(
- *, event: Any, origin: Any, reason: Any, failure_class: Any, wait_seconds: Any,
- ) -> dict[str, str] | None:
- """Closed dimensions for one event; ``None`` for an event outside the set (never recorded)."""
- from .shared_metrics_fields import compression_failure_class
- name = _closed(event, PREPARED_COMPACTION_EVENTS, "")
- if not name:
- return None
- return {
- "event": name,
- "failure_class": "none" if failure_class is None else compression_failure_class("failed", failure_class),
- "origin": _closed(origin, PREPARED_COMPACTION_ORIGINS, "none"),
- "reason": _closed(reason, PREPARED_COMPACTION_REASONS, "none"),
- "wait_bucket": wait_bucket(wait_seconds),
- }
- def record_prepared_compaction(
- event: str, *, origin: str | None = None, reason: str | None = None, failure_class: str | None = None,
- wait_seconds: float | None = None,
- ) -> None:
- """Count one prepared-compaction event (no-op unless shared metrics are on; never raises)."""
- from .shared_metrics_events import _emit
- _emit(
- PREPARED_COMPACTION_MARK, prepared_compaction_fields, event=event, origin=origin, reason=reason,
- failure_class=failure_class, wait_seconds=wait_seconds,
- )
|