detectkit 0.16.3__tar.gz → 0.17.0__tar.gz

{detectkit-0.16.3/detectkit.egg-info → detectkit-0.17.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: detectkit
-Version: 0.16.3
+Version: 0.17.0
 Summary: Metric monitoring with automatic anomaly detection
 Author: detectkit team
 License: MIT
@@ -185,6 +185,7 @@ for r in results:
 - [Configuration Guide](docs/guides/configuration.md) — all config options
 - [Detectors Guide](docs/guides/detectors.md) — choosing the right detector
 - [Alerting Guide](docs/guides/alerting.md) — channels, mentions, cooldown, recovery
+- [Reading Alerts](docs/guides/reading-alerts.md) — what a received alert means (for stakeholders)
 - [CLI Reference](docs/reference/cli.md) — command-line documentation
 - [Examples](docs/examples/) — real-world monitoring scenarios
 - [Changelog](CHANGELOG.md) — version history

{detectkit-0.16.3 → detectkit-0.17.0}/README.md

@@ -117,6 +117,7 @@ for r in results:
 - [Configuration Guide](docs/guides/configuration.md) — all config options
 - [Detectors Guide](docs/guides/detectors.md) — choosing the right detector
 - [Alerting Guide](docs/guides/alerting.md) — channels, mentions, cooldown, recovery
+- [Reading Alerts](docs/guides/reading-alerts.md) — what a received alert means (for stakeholders)
 - [CLI Reference](docs/reference/cli.md) — command-line documentation
 - [Examples](docs/examples/) — real-world monitoring scenarios
 - [Changelog](CHANGELOG.md) — version history

{detectkit-0.16.3 → detectkit-0.17.0}/detectkit/__init__.py

@@ -4,7 +4,7 @@ detectk - Anomaly Detection for Time-Series Metrics
 A Python library for data analysts and engineers to monitor metrics with automatic anomaly detection.
 """
 
-__version__ = "0.16.3"
+__version__ = "0.17.0"
 
 from detectkit.core.interval import Interval
 from detectkit.core.models import ColumnDefinition, TableModel

{detectkit-0.16.3 → detectkit-0.17.0}/detectkit/alerting/channels/base.py

@@ -92,6 +92,18 @@ class AlertData:
     direction_policy: str | None = None
     consecutive_required: int | None = None
     detector_count: int = 1
+    # Incident timing — answers "how long has this been going on". The metric
+    # ``interval_seconds`` lets the message express the streak in wall-clock
+    # time; ``onset_timestamp`` is the first timestamp of the current anomalous
+    # run (anomaly) / the just-ended incident (recovery); ``streak_capped`` is
+    # True when the run is at least as long as the orchestrator's lookback
+    # window, so the duration is rendered as a lower bound ("over …"). The
+    # consecutive streak length itself rides on ``consecutive_count`` (the true
+    # run length, resolved at fire time). All default to None/False so
+    # direct-API callers and non-anomaly alerts render unchanged.
+    interval_seconds: int | None = None
+    onset_timestamp: Any | None = None
+    streak_capped: bool = False
 
 
 class BaseAlertChannel(ABC):
@@ -165,8 +177,18 @@ class BaseAlertChannel(ABC):
         - {direction} — observed/locked direction of the anomaly
         - {direction_policy} — configured direction rule ("same"/"any"/...)
         - {min_detectors} — configured quorum threshold (the rule)
-        - {consecutive_count} — observed consecutive points
+        - {consecutive_count} — true consecutive streak length (resolved at
+          fire time, not capped at the rule's threshold)
         - {consecutive_required} — configured consecutive threshold (rule)
+        - {interval_display} — metric interval as a string (e.g. "10min")
+        - {duration_display} — how long the streak/incident lasted
+          (e.g. "2h 30m"; "over …" when it predates the lookback window)
+        - {onset_display} / {started_display} — first timestamp of the run
+          ({started_display} adds "or earlier" when the run is capped)
+        - {anomaly_lead} / {recovery_lead} — the ready-made plain-language
+          lead sentence ("Anomalous for …" / "… Incident lasted …")
+        - {window_line} — "Started: … | Latest/Cleared: …" (or a single
+          "Detected at: …" line when the onset is unknown)
         - {severity}
         - {status}
 
@@ -228,22 +250,27 @@ class BaseAlertChannel(ABC):
         """
         import math
         from datetime import datetime
+        from zoneinfo import ZoneInfo
 
         import numpy as np
 
-        # Format timestamp to string
-        ts = alert_data.timestamp
-        if isinstance(ts, np.datetime64):
-            ts = ts.astype(datetime)
-
-        # Convert naive UTC timestamp to target timezone if specified
-        if alert_data.timezone:
-            from zoneinfo import ZoneInfo
-
-            ts = ts.replace(tzinfo=ZoneInfo("UTC")).astimezone(ZoneInfo(alert_data.timezone))
-            ts_str = f"{ts.strftime('%Y-%m-%d %H:%M:%S')} ({alert_data.timezone})"
-        else:
-            ts_str = ts.strftime("%Y-%m-%d %H:%M:%S")
+        def _fmt_ts(value: Any) -> str:
+            """Format a timestamp the same way for the main point and the onset:
+            naive UTC → target timezone, with a ``(tz)`` suffix when set."""
+            if value is None:
+                return ""
+            t = value
+            if isinstance(t, np.datetime64):
+                t = t.astype("datetime64[ms]").astype(datetime)
+            if not isinstance(t, datetime):
+                return str(t)
+            if alert_data.timezone:
+                t = t.replace(tzinfo=ZoneInfo("UTC")).astimezone(ZoneInfo(alert_data.timezone))
+                return f"{t.strftime('%Y-%m-%d %H:%M:%S')} ({alert_data.timezone})"
+            return t.strftime("%Y-%m-%d %H:%M:%S")
+
+        ts_str = _fmt_ts(alert_data.timestamp)
+        onset_str = _fmt_ts(alert_data.onset_timestamp)
 
         # Format confidence interval
         if alert_data.confidence_lower is not None and alert_data.confidence_upper is not None:
@@ -287,6 +314,66 @@ class BaseAlertChannel(ABC):
         )
         direction_policy = alert_data.direction_policy or alert_data.direction
 
+        # Incident timing — the "how long has this been going on" story shared by
+        # every channel. ``consecutive_count`` carries the *true* streak length
+        # (resolved at fire time); together with the metric interval it becomes a
+        # wall-clock duration and a plain-language lead. ``streak_capped`` means
+        # the run is at least as long as the orchestrator's lookback window, so
+        # the duration/started values render as lower bounds. Degrades cleanly to
+        # the legacy "Latest X/Y consecutive points met the quorum." lead when no
+        # interval is wired in (direct-API callers).
+        from detectkit.core.interval import Interval
+        from detectkit.utils.datetime_utils import format_duration
+
+        interval_seconds = alert_data.interval_seconds
+        streak = alert_data.consecutive_count or 0
+        capped = alert_data.streak_capped
+        interval_display = str(Interval(interval_seconds)) if interval_seconds else ""
+
+        if interval_seconds and streak >= 1:
+            duration_display = format_duration(streak * interval_seconds)
+            if capped:
+                duration_display = f"over {duration_display}"
+            streak_display = f"{streak}+" if capped else f"{streak}"
+            started_display = f"{onset_str} or earlier" if (capped and onset_str) else onset_str
+            intervals_word = "interval" if streak == 1 else "intervals"
+            anomaly_lead = (
+                f"Anomalous for {duration_display} — "
+                f"{streak_display} consecutive {interval_display} {intervals_word}."
+            )
+            recovery_lead = (
+                "The alert condition no longer holds — the metric is back within "
+                f"expected bounds. Incident lasted {duration_display} "
+                f"({streak_display} consecutive {interval_display} {intervals_word})."
+            )
+        else:
+            duration_display = ""
+            streak_display = f"{streak}" if streak else ""
+            started_display = onset_str
+            anomaly_lead = (
+                f"Latest {alert_data.consecutive_count}/{consecutive_required} "
+                "consecutive points met the quorum."
+            )
+            recovery_lead = (
+                "The alert condition no longer holds — the metric is back within "
+                "expected bounds."
+            )
+
+        # Kind-aware "window" line for the plain-text templates: the anomalous
+        # span (onset → latest/cleared) when known, else the single point.
+        kind = self.status_kind(alert_data)
+        if started_display and kind == "anomaly":
+            window_line = f"Started: {started_display} | Latest: {ts_str}\n"
+        elif started_display and kind == "recovery":
+            window_line = f"Started: {started_display} | Cleared: {ts_str}\n"
+        else:
+            window_label = {
+                "recovery": "Cleared at",
+                "no_data": "Expected at",
+                "error": "Detected at",
+            }.get(kind, "Detected at")
+            window_line = f"{window_label}: {ts_str}\n"
+
         # Display-safe value: stays usable even when value is None/NaN (no-data).
         raw_value = alert_data.value
         if raw_value is None or (isinstance(raw_value, float) and math.isnan(raw_value)):
@@ -350,6 +437,15 @@ class BaseAlertChannel(ABC):
             "severity": alert_data.severity,
             "consecutive_count": alert_data.consecutive_count,
             "consecutive_required": consecutive_required,
+            "interval_display": interval_display,
+            "duration_display": duration_display,
+            "streak_display": streak_display,
+            "streak_capped": capped,
+            "onset_display": onset_str,
+            "started_display": started_display,
+            "anomaly_lead": anomaly_lead,
+            "recovery_lead": recovery_lead,
+            "window_line": window_line,
             "status": status,
             "error_type": alert_data.error_type or "",
             "error_message": alert_data.error_message or "",
@@ -472,16 +568,14 @@ class BaseAlertChannel(ABC):
         return (
             "🔴 {project_name_prefix}Alert: {metric_name}\n"
             "{description_line}"
-            "Quorum {detector_count}/{min_detectors} · "
-            "direction {direction} (policy {direction_policy}) · "
-            "consecutive {consecutive_count}/{consecutive_required}\n"
+            "{anomaly_lead}\n"
             "Rule: min_detectors={min_detectors} · "
             "direction={direction_policy} · consecutive={consecutive_required}\n"
             "\n"
-            "Latest point (evidence):\n"
-            "· Time: {timestamp}\n"
-            "· Value: {value_display} | Expected: {expected_range}\n"
-            "· Severity: {severity:.2f}\n"
+            "Value: {value_display} | Expected: {expected_range}\n"
+            "Quorum: {detector_count}/{min_detectors} · {direction}\n"
+            "Severity: {severity:.2f}\n"
+            "{window_line}"
             "Detectors: {detector_name}\n"
             "Parameters: {detector_params}\n"
             "{dashboard_line}"
@@ -499,14 +593,12 @@ class BaseAlertChannel(ABC):
         return (
             "🟢 {project_name_prefix}Alert cleared: {metric_name}\n"
             "{description_line}"
-            "The alert condition no longer holds — "
-            "the metric is back within expected bounds.\n"
+            "{recovery_lead}\n"
             "Rule: min_detectors={min_detectors} · "
             "direction={direction_policy} · consecutive={consecutive_required}\n"
             "\n"
-            "Latest point:\n"
-            "· Time: {timestamp}\n"
-            "· Value: {value_display} | Expected: {expected_range}\n"
+            "Value: {value_display} | Expected: {expected_range}\n"
+            "{window_line}"
             "Detectors: {detector_name}\n"
             "{dashboard_line}"
             "{help_line}"

{detectkit-0.16.3 → detectkit-0.17.0}/detectkit/alerting/channels/email.py

@@ -315,42 +315,38 @@ class EmailChannel(BaseAlertChannel):
             parts.append(self._lead_html(ctx["description"]))
 
         if kind == "anomaly":
+            # Description (how long it's been going on) leads; the Rule chip sits
+            # right above the stat grid it explains.
+            parts.append(self._lead_html(ctx["anomaly_lead"]))
             parts.append(self._rule_html(ctx))
-            parts.append(
-                self._lead_html(
-                    f"Latest {ctx['consecutive_count']}/{ctx['consecutive_required']} "
-                    "consecutive points met the quorum."
-                )
-            )
-            parts.append(
-                self._stat_grid(
-                    [
-                        ("Value", ctx["value_display"]),
-                        ("Expected", ctx["expected_range"]),
-                        ("Severity", f"{alert_data.severity:.2f}"),
-                        ("Detected at", ctx["timestamp"]),
-                    ]
-                )
-            )
+            stats = [
+                ("Value", ctx["value_display"]),
+                ("Expected", ctx["expected_range"]),
+                ("Severity", f"{alert_data.severity:.2f}"),
+                ("Quorum", f"{ctx['detector_count']}/{ctx['min_detectors']} · {ctx['direction']}"),
+            ]
+            if ctx["started_display"]:
+                stats.append(("Started", ctx["started_display"]))
+                stats.append(("Latest", ctx["timestamp"]))
+            else:
+                stats.append(("Detected at", ctx["timestamp"]))
+            parts.append(self._stat_grid(stats))
             if ctx["detector_params"]:
                 parts.append(self._params_html(ctx["detector_name"], ctx["detector_params"]))
         elif kind == "recovery":
-            lead = (
-                "The alert condition no longer holds — the metric is back within "
-                "expected bounds."
-            )
-            parts.append(self._lead_html(lead))
+            parts.append(self._lead_html(ctx["recovery_lead"]))
             parts.append(self._rule_html(ctx))
-            parts.append(
-                self._stat_grid(
-                    [
-                        ("Value", ctx["value_display"]),
-                        ("Expected", ctx["expected_range"]),
-                        ("Detector", ctx["detector_name"]),
-                        ("Cleared at", ctx["timestamp"]),
-                    ]
-                )
-            )
+            stats = [
+                ("Value", ctx["value_display"]),
+                ("Expected", ctx["expected_range"]),
+            ]
+            if ctx["started_display"]:
+                stats.append(("Started", ctx["started_display"]))
+                stats.append(("Cleared", ctx["timestamp"]))
+            else:
+                stats.append(("Cleared at", ctx["timestamp"]))
+            stats.append(("Detector", ctx["detector_name"]))
+            parts.append(self._stat_grid(stats))
         elif kind == "no_data":
             lead = "Query returned no datapoint for the latest expected interval."
             parts.append(self._lead_html(lead))

{detectkit-0.16.3 → detectkit-0.17.0}/detectkit/alerting/channels/telegram.py

@@ -24,9 +24,10 @@ class TelegramChannel(BaseAlertChannel):
 
     Sends formatted messages to a Telegram chat using a bot token. The default
     (no custom ``template``) message is a structured **HTML** layout — a colored
-    status dot, a bold headline, the rule that fired, then the evidence
-    (value / expected / severity / time / detector / params) in ``<code>``,
-    plus an optional "Open dashboard" link and @mentions.
+    status dot, a bold headline, the lead (how long the anomaly has been
+    running) followed by the rule that fired, then the evidence
+    (value / expected / quorum / severity / started → latest / detector /
+    params) in ``<code>``, plus an optional "Open dashboard" link and @mentions.
 
     HTML is the default ``parse_mode`` because the legacy ``Markdown`` mode
     breaks on the detector params JSON (an unmatched ``_`` in e.g.
@@ -161,11 +162,9 @@ class TelegramChannel(BaseAlertChannel):
         lines.append("")  # blank line
 
         if kind == "anomaly":
-            lines.append(
-                f"<b>Quorum</b> {ctx['detector_count']}/{ctx['min_detectors']} · "
-                f"direction <b>{esc(ctx['direction'])}</b> · "
-                f"<b>{ctx['consecutive_count']}/{ctx['consecutive_required']}</b> consecutive"
-            )
+            # Description (how long it's been going on) leads; the Rule chip sits
+            # right above the evidence it explains.
+            lines.append(esc(ctx["anomaly_lead"]))
             lines.append(
                 f"<b>Rule</b> <code>min_detectors={ctx['min_detectors']} · "
                 f"direction={esc(ctx['direction_policy'])} · "
@@ -176,17 +175,24 @@ class TelegramChannel(BaseAlertChannel):
                 f"• Value: <code>{esc(ctx['value_display'])}</code> · "
                 f"Expected: <code>{esc(ctx['expected_range'])}</code>"
             )
+            lines.append(
+                f"• Quorum: <code>{ctx['detector_count']}/{ctx['min_detectors']} · "
+                f"{esc(ctx['direction'])}</code>"
+            )
             lines.append(f"• Severity: <code>{alert_data.severity:.2f}</code>")
-            lines.append(f"• Time: <code>{esc(ctx['timestamp'])}</code>")
+            if ctx["started_display"]:
+                lines.append(
+                    f"• Started: <code>{esc(ctx['started_display'])}</code> · "
+                    f"Latest: <code>{esc(ctx['timestamp'])}</code>"
+                )
+            else:
+                lines.append(f"• Time: <code>{esc(ctx['timestamp'])}</code>")
             lines.append(f"• Detector: <code>{esc(ctx['detector_name'])}</code>")
             if ctx["detector_params"]:
                 params = self._cap(ctx["detector_params"], _PARAMS_CAP)
                 lines.append(f"• Parameters: <code>{esc(params)}</code>")
         elif kind == "recovery":
-            lines.append(
-                "The alert condition no longer holds — the metric is back within "
-                "expected bounds."
-            )
+            lines.append(esc(ctx["recovery_lead"]))
             lines.append(
                 f"<b>Rule</b> <code>min_detectors={ctx['min_detectors']} · "
                 f"direction={esc(ctx['direction_policy'])} · "
@@ -197,7 +203,13 @@ class TelegramChannel(BaseAlertChannel):
                 f"• Value: <code>{esc(ctx['value_display'])}</code> · "
                 f"Expected: <code>{esc(ctx['expected_range'])}</code>"
             )
-            lines.append(f"• Time: <code>{esc(ctx['timestamp'])}</code>")
+            if ctx["started_display"]:
+                lines.append(
+                    f"• Started: <code>{esc(ctx['started_display'])}</code> · "
+                    f"Cleared: <code>{esc(ctx['timestamp'])}</code>"
+                )
+            else:
+                lines.append(f"• Cleared: <code>{esc(ctx['timestamp'])}</code>")
             lines.append(f"• Detector: <code>{esc(ctx['detector_name'])}</code>")
         elif kind == "no_data":
             lines.append("Query returned no datapoint for the latest expected interval.")

{detectkit-0.16.3 → detectkit-0.17.0}/detectkit/alerting/channels/webhook.py

@@ -27,9 +27,11 @@ class WebhookChannel(BaseAlertChannel):
 
     Rendering: the default (no custom ``template``) payload is a single
     **Slack/Mattermost message attachment** — a colored accent bar, a title,
-    a short markdown lead, and a compact **fields grid** (Value / Expected /
-    Quorum / Severity, then full-width Detected-at / Detectors / Parameters),
-    branded with a ``footer`` + ``footer_icon``. This renders richly on both
+    a short markdown lead (how long the anomaly has been running) with the
+    **Rule** chip beneath it, and a compact **fields grid** (Value / Expected /
+    Quorum / Severity / Started / Latest — Started / Cleared on recovery — then
+    full-width Detectors / Parameters), branded with a ``footer`` +
+    ``footer_icon``. This renders richly on both
     Slack and Mattermost from one payload. A custom ``template`` degrades to a
     plain text-only attachment (the template is one opaque string that can't be
     sliced into fields), keeping the color, title and branding.
@@ -267,27 +269,32 @@ class WebhookChannel(BaseAlertChannel):
         )
 
         if kind == "anomaly":
-            lead = (
-                f"{rule_chip}\n"
-                f"Latest {ctx['consecutive_count']}/{ctx['consecutive_required']} "
-                "consecutive points met the quorum."
-            )
+            # Description (how long it's been going on) leads; the Rule chip sits
+            # right above the value/expected fields it explains.
+            lead = f"{ctx['anomaly_lead']}\n{rule_chip}"
             short("Value", code(ctx["value_display"]))
             short("Expected", code(ctx["expected_range"]))
             short("Quorum", f"{ctx['detector_count']}/{ctx['min_detectors']} · {ctx['direction']}")
             short("Severity", f"{alert_data.severity:.2f}")
-            full("Detected at", ctx["timestamp"])
+            # The problematic span: when it started and the latest point in it.
+            if ctx["started_display"]:
+                short("Started", ctx["started_display"])
+                short("Latest", ctx["timestamp"])
+            else:
+                full("Detected at", ctx["timestamp"])
             full("Detectors", code(ctx["detector_name"]))
             if ctx["detector_params"]:
                 full("Parameters", f"```{ctx['detector_params']}```")
         elif kind == "recovery":
-            lead = (
-                "The alert condition no longer holds — the metric is back within "
-                f"expected bounds.\n{rule_chip}"
-            )
+            lead = f"{ctx['recovery_lead']}\n{rule_chip}"
             short("Value", code(ctx["value_display"]))
             short("Expected", code(ctx["expected_range"]))
-            full("Detected at", ctx["timestamp"])
+            # The incident span: when it started and when it cleared.
+            if ctx["started_display"]:
+                short("Started", ctx["started_display"])
+                short("Cleared", ctx["timestamp"])
+            else:
+                full("Cleared at", ctx["timestamp"])
             full("Detectors", code(ctx["detector_name"]))
         elif kind == "no_data":
             lead = "Query returned no datapoint for the latest expected interval."
@@ -383,16 +390,14 @@ class WebhookChannel(BaseAlertChannel):
         """
         return (
             "{description_line}"
-            "Quorum {detector_count}/{min_detectors} · "
-            "direction {direction} (policy {direction_policy}) · "
-            "consecutive {consecutive_count}/{consecutive_required}\n"
+            "{anomaly_lead}\n"
             "Rule: min_detectors={min_detectors} · "
             "direction={direction_policy} · consecutive={consecutive_required}\n"
             "\n"
-            "Latest point (evidence):\n"
-            "· Time: {timestamp}\n"
-            "· Value: {value_display} | Expected: {expected_range}\n"
-            "· Severity: {severity:.2f}\n"
+            "Value: {value_display} | Expected: {expected_range}\n"
+            "Quorum: {detector_count}/{min_detectors} · {direction}\n"
+            "Severity: {severity:.2f}\n"
+            "{window_line}"
             "Detectors: {detector_name}\n"
             "Parameters: {detector_params}\n"
             "{dashboard_line}"
@@ -406,14 +411,12 @@ class WebhookChannel(BaseAlertChannel):
         """
         return (
             "{description_line}"
-            "The alert condition no longer holds — "
-            "the metric is back within expected bounds.\n"
+            "{recovery_lead}\n"
             "Rule: min_detectors={min_detectors} · "
             "direction={direction_policy} · consecutive={consecutive_required}\n"
             "\n"
-            "Latest point:\n"
-            "· Time: {timestamp}\n"
-            "· Value: {value_display} | Expected: {expected_range}\n"
+            "Value: {value_display} | Expected: {expected_range}\n"
+            "{window_line}"
             "Detectors: {detector_name}\n"
             "{dashboard_line}"
             "{help_line}"

{detectkit-0.16.3 → detectkit-0.17.0}/detectkit/alerting/orchestrator/_base.py

@@ -10,6 +10,15 @@ from detectkit.alerting.orchestrator._types import (
 )
 from detectkit.core.interval import Interval
 
+# How far back the orchestrator looks to reconstruct the *true* length of an
+# anomalous run when an alert fires / clears. The decision itself only needs
+# ``consecutive_anomalies`` points, but the message reports "how long has this
+# been going on", which needs the full streak. Bounded so a metric stuck
+# anomalous for a very long time never loads unboundedly — past this the run is
+# reported as a lower bound ("over …"). Only queried on fire/recovery, never on
+# the hot no-alert path.
+STREAK_LOOKBACK_POINTS = 1000
+
 
 class _OrchestratorBase:
     def __init__(

{detectkit-0.16.3 → detectkit-0.17.0}/detectkit/alerting/orchestrator/_decision.py

@@ -34,8 +34,8 @@ from datetime import datetime, timezone
 import numpy as np
 
 from detectkit.alerting.channels.base import AlertData
-from detectkit.alerting.orchestrator._base import _OrchestratorBase
-from detectkit.alerting.orchestrator._types import DetectionRecord
+from detectkit.alerting.orchestrator._base import STREAK_LOOKBACK_POINTS, _OrchestratorBase
+from detectkit.alerting.orchestrator._types import DetectionRecord, hydrate_detection_records
 from detectkit.utils.datetime_utils import now_utc, to_aware_utc
 
 
@@ -70,7 +70,46 @@ class _DecisionMixin(_OrchestratorBase):
         if not latest_quorum or consecutive < self.conditions.consecutive_anomalies:
             return False, None
 
-        return True, self._build_alert_data(latest_quorum, consecutive, direction)
+        # The decision is made; now resolve the *true* streak length/onset for
+        # the message (the shallow alert window caps ``consecutive`` at the rule
+        # threshold, which can't answer "how long has this been going on").
+        streak, onset_ts, capped = self._resolve_streak(latest_quorum[0].timestamp)
+        return True, self._build_alert_data(latest_quorum, streak, direction, onset_ts, capped)
+
+    def _resolve_streak(self, latest_ts: np.datetime64) -> tuple[int, np.datetime64, bool]:
+        """Resolve the full anomalous run ending at *latest_ts*.
+
+        Loads up to :data:`STREAK_LOOKBACK_POINTS` detections and re-walks the
+        same direction-aware quorum logic used to fire, so the message can report
+        the real onset/duration rather than the shallow alert-window count.
+        Returns ``(streak_count, onset_timestamp, capped)`` — ``capped`` is True
+        when the run fills the whole lookback window (onset is older than we saw).
+        Only runs when an alert actually fires, so the hot no-alert path is
+        untouched.
+        """
+        step = np.timedelta64(self.interval.seconds, "s")
+        if not self.internal:
+            # Direct-API path with no DB to walk: report the rule's required
+            # length so the message still carries a duration.
+            n = max(self.conditions.consecutive_anomalies, 1)
+            return n, latest_ts - step * (n - 1), False
+
+        last_point = latest_ts.astype("datetime64[ms]").astype(datetime)
+        rows = self.internal.get_recent_detections(
+            metric_name=self.metric_name,
+            last_point=last_point,
+            num_points=STREAK_LOOKBACK_POINTS,
+        )
+        records = hydrate_detection_records(rows)
+        if not records:
+            return 1, latest_ts, False
+
+        by_time = self._group_by_timestamp(records)
+        timestamps_sorted = sorted(by_time.keys(), reverse=True)
+        count, _, _ = self._count_consecutive_anomalies(by_time, timestamps_sorted)
+        count = max(count, 1)
+        capped = count >= STREAK_LOOKBACK_POINTS
+        return count, latest_ts - step * (count - 1), capped
 
     def _quorum_at(
         self,
@@ -185,6 +224,8 @@ class _DecisionMixin(_OrchestratorBase):
         anomalies: list[DetectionRecord],
         consecutive_count: int,
         direction: str | None,
+        onset_timestamp: np.datetime64 | None = None,
+        streak_capped: bool = False,
     ) -> AlertData:
         primary = self._primary_record(anomalies)
 
@@ -249,6 +290,10 @@ class _DecisionMixin(_OrchestratorBase):
             direction_policy=self.conditions.direction,
             consecutive_required=self.conditions.consecutive_anomalies,
             detector_count=len(anomalies),
+            # Incident timing for the "how long has this been going on" line.
+            interval_seconds=self.interval.seconds,
+            onset_timestamp=onset_timestamp,
+            streak_capped=streak_capped,
         )
 
     def should_alert_no_data(
@@ -304,6 +349,7 @@ class _DecisionMixin(_OrchestratorBase):
             links=self.links,
             project_name=self.project_name,
             help_url=self.help_url,
+            interval_seconds=self.interval.seconds,
         )
 
     def get_last_complete_point(self, now: datetime | None = None) -> datetime: