feat(health): metrics-stale signal + status-transition timestamps; spec now matches heartbeat-liveness code

2026-07-08 16:21:30 -04:00
parent 15d91d760f
commit c73b7faa11
7 changed files with 199 additions and 16 deletions
@@ -44,4 +44,23 @@ public sealed record SiteHealthState
    public long LastSequenceNumber { get; init; }
    /// <summary>Gets a value indicating whether the site is currently considered online.</summary>
    public bool IsOnline { get; init; }
+
+    /// <summary>
+    /// Gets a value indicating whether the site is online (heartbeats still
+    /// arriving) but has sent no full <see cref="SiteHealthReport"/> within
+    /// <see cref="HealthMonitoringOptions.MetricsStaleTimeout"/>. This is a signal
+    /// <em>distinct</em> from liveness: a site whose HealthReportSender died keeps
+    /// heartbeating and would otherwise show "online with frozen metrics forever".
+    /// Cleared whenever a fresh report is processed. Heartbeats never set or clear
+    /// it — they say nothing about the metrics pipeline.
+    /// </summary>
+    public bool IsMetricsStale { get; init; }
+
+    /// <summary>
+    /// Gets the instant of the last online↔offline flip, or <c>null</c> if the
+    /// site has never changed status since it was first observed. Answers "when
+    /// did this site drop / come back". Not moved by report/heartbeat traffic that
+    /// leaves the online/offline status unchanged, nor by the metrics-stale flag.
+    /// </summary>
+    public DateTimeOffset? LastStatusChangeAt { get; init; }
 }