detectkit 0.34.0__tar.gz → 0.35.0__tar.gz

{detectkit-0.34.0/detectkit.egg-info → detectkit-0.35.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: detectkit
-Version: 0.34.0
+Version: 0.35.0
 Summary: Metric monitoring with automatic anomaly detection
 Author: detectkit team
 License: MIT

{detectkit-0.34.0 → detectkit-0.35.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.34.0"
+__version__ = "0.35.0"
 
 from detectkit.core.interval import Interval
 from detectkit.core.models import ColumnDefinition, TableModel

{detectkit-0.34.0 → detectkit-0.35.0}/detectkit/alerting/channels/base.py

@@ -183,12 +183,16 @@ class BaseAlertChannel(ABC):
         - {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)
+        - {onset_display} / {started_display} — first anomalous timestamp of
+          the run ({started_display} adds "or earlier" when the run is capped)
+        - {fired_display} — on-grid moment the alert first fired
+          (onset + (consecutive_required − 1) × interval); empty when the run
+          is capped or timing isn't wired in
         - {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)
+        - {window_line} — "Anomaly began: … | Latest reading: …" (anomaly) /
+          "Anomaly began: … | Alert fired: … | Recovered: …" (recovery), or a
+          single "Detected at: …" line when the onset is unknown
         - {severity}
         - {status}
 
@@ -249,7 +253,7 @@ class BaseAlertChannel(ABC):
         templates use, plus a few extras (``dashboard_url``, ``dashboard_line``).
         """
         import math
-        from datetime import datetime
+        from datetime import datetime, timedelta
         from zoneinfo import ZoneInfo
 
         import numpy as np
@@ -269,6 +273,14 @@ class BaseAlertChannel(ABC):
                 return f"{t.strftime('%Y-%m-%d %H:%M:%S')} ({alert_data.timezone})"
             return t.strftime("%Y-%m-%d %H:%M:%S")
 
+        def _shift_ts(value: Any, seconds: int) -> Any:
+            """Shift a timestamp forward by *seconds*, preserving its type."""
+            if isinstance(value, np.datetime64):
+                return value + np.timedelta64(int(seconds), "s")
+            if isinstance(value, datetime):
+                return value + timedelta(seconds=int(seconds))
+            return value
+
         ts_str = _fmt_ts(alert_data.timestamp)
         onset_str = _fmt_ts(alert_data.onset_timestamp)
 
@@ -359,13 +371,31 @@ class BaseAlertChannel(ABC):
                 "expected bounds."
             )
 
+        # "Alert fired" — the on-grid moment the rule's consecutive threshold was
+        # first met: onset + (consecutive_required - 1) * interval. Recovery
+        # messages render it as the middle of the "anomaly began → alert fired →
+        # recovered" timeline so a stakeholder can tell the onset apart from when
+        # detectkit actually notified. Skipped when the run is capped (onset is
+        # only a lower bound, so the fire time is unknown) or timing isn't wired
+        # in (direct-API callers). The firing message doesn't show it: there it
+        # coincides with the latest point the alert is firing on.
+        fired_display = ""
+        if alert_data.onset_timestamp is not None and interval_seconds and not capped:
+            req = (
+                consecutive_required if (consecutive_required and consecutive_required >= 1) else 1
+            )
+            fired_ts = _shift_ts(alert_data.onset_timestamp, (req - 1) * interval_seconds)
+            fired_display = _fmt_ts(fired_ts)
+
         # Kind-aware "window" line for the plain-text templates: the anomalous
-        # span (onset → latest/cleared) when known, else the single point.
+        # span (began → latest, or began → fired → recovered) 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"
+            window_line = f"Anomaly began: {started_display} | Latest reading: {ts_str}\n"
         elif started_display and kind == "recovery":
-            window_line = f"Started: {started_display} | Cleared: {ts_str}\n"
+            fired_part = f"Alert fired: {fired_display} | " if fired_display else ""
+            window_line = f"Anomaly began: {started_display} | {fired_part}Recovered: {ts_str}\n"
         else:
             window_label = {
                 "recovery": "Cleared at",
@@ -443,6 +473,7 @@ class BaseAlertChannel(ABC):
             "streak_capped": capped,
             "onset_display": onset_str,
             "started_display": started_display,
+            "fired_display": fired_display,
             "anomaly_lead": anomaly_lead,
             "recovery_lead": recovery_lead,
             "window_line": window_line,

{detectkit-0.34.0 → detectkit-0.35.0}/detectkit/alerting/channels/email.py

@@ -326,8 +326,8 @@ class EmailChannel(BaseAlertChannel):
                 ("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"]))
+                stats.append(("Anomaly began", ctx["started_display"]))
+                stats.append(("Latest reading", ctx["timestamp"]))
             else:
                 stats.append(("Detected at", ctx["timestamp"]))
             parts.append(self._stat_grid(stats))
@@ -341,8 +341,10 @@ class EmailChannel(BaseAlertChannel):
                 ("Expected", ctx["expected_range"]),
             ]
             if ctx["started_display"]:
-                stats.append(("Started", ctx["started_display"]))
-                stats.append(("Cleared", ctx["timestamp"]))
+                stats.append(("Anomaly began", ctx["started_display"]))
+                if ctx["fired_display"]:
+                    stats.append(("Alert fired", ctx["fired_display"]))
+                stats.append(("Recovered", ctx["timestamp"]))
             else:
                 stats.append(("Cleared at", ctx["timestamp"]))
             stats.append(("Detector", ctx["detector_name"]))

{detectkit-0.34.0 → detectkit-0.35.0}/detectkit/alerting/channels/telegram.py

@@ -182,8 +182,8 @@ class TelegramChannel(BaseAlertChannel):
             lines.append(f"• Severity: <code>{alert_data.severity:.2f}</code>")
             if ctx["started_display"]:
                 lines.append(
-                    f"• Started: <code>{esc(ctx['started_display'])}</code> · "
-                    f"Latest: <code>{esc(ctx['timestamp'])}</code>"
+                    f"• Anomaly began: <code>{esc(ctx['started_display'])}</code> · "
+                    f"Latest reading: <code>{esc(ctx['timestamp'])}</code>"
                 )
             else:
                 lines.append(f"• Time: <code>{esc(ctx['timestamp'])}</code>")
@@ -204,12 +204,17 @@ class TelegramChannel(BaseAlertChannel):
                 f"Expected: <code>{esc(ctx['expected_range'])}</code>"
             )
             if ctx["started_display"]:
+                fired = (
+                    f"Alert fired: <code>{esc(ctx['fired_display'])}</code> · "
+                    if ctx["fired_display"]
+                    else ""
+                )
                 lines.append(
-                    f"• Started: <code>{esc(ctx['started_display'])}</code> · "
-                    f"Cleared: <code>{esc(ctx['timestamp'])}</code>"
+                    f"• Anomaly began: <code>{esc(ctx['started_display'])}</code> · "
+                    f"{fired}Recovered: <code>{esc(ctx['timestamp'])}</code>"
                 )
             else:
-                lines.append(f"• Cleared: <code>{esc(ctx['timestamp'])}</code>")
+                lines.append(f"• Recovered: <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.34.0 → detectkit-0.35.0}/detectkit/alerting/channels/webhook.py

@@ -276,10 +276,10 @@ class WebhookChannel(BaseAlertChannel):
             short("Expected", code(ctx["expected_range"]))
             short("Quorum", f"{ctx['detector_count']}/{ctx['min_detectors']} · {ctx['direction']}")
             short("Severity", f"{alert_data.severity:.2f}")
-            # The problematic span: when it started and the latest point in it.
+            # The problematic span: when the anomaly began and its latest point.
             if ctx["started_display"]:
-                short("Started", ctx["started_display"])
-                short("Latest", ctx["timestamp"])
+                short("Anomaly began", ctx["started_display"])
+                short("Latest reading", ctx["timestamp"])
             else:
                 full("Detected at", ctx["timestamp"])
             full("Detectors", code(ctx["detector_name"]))
@@ -289,10 +289,12 @@ class WebhookChannel(BaseAlertChannel):
             lead = f"{ctx['recovery_lead']}\n{rule_chip}"
             short("Value", code(ctx["value_display"]))
             short("Expected", code(ctx["expected_range"]))
-            # The incident span: when it started and when it cleared.
+            # The incident timeline: anomaly onset → when the alert fired →
+            # when it recovered. ``short`` skips the fired field when unknown.
             if ctx["started_display"]:
-                short("Started", ctx["started_display"])
-                short("Cleared", ctx["timestamp"])
+                short("Anomaly began", ctx["started_display"])
+                short("Alert fired", ctx["fired_display"])
+                short("Recovered", ctx["timestamp"])
             else:
                 full("Cleared at", ctx["timestamp"])
             full("Detectors", code(ctx["detector_name"]))

{detectkit-0.34.0 → detectkit-0.35.0}/detectkit/cli/assets/claude/rules/alerting.md

@@ -196,15 +196,15 @@ leads with a colored **status circle** — 🔴 anomaly, 🟢 recovery, 🟡 no-
   status-colored accent bar, a clickable title (the metric; links to
   `dashboard_url` when set), a short markdown lead (the duration sentence — see
   "Incident timing" below) with the **Rule** chip beneath it, and a compact
-  fields grid: short fields Value / Expected / Quorum / Severity / Started /
-  Latest (Started / Cleared on recovery), then full-width Detectors / Parameters,
+  fields grid: short fields Value / Expected / Quorum / Severity / Anomaly began /
+  Latest reading (Anomaly began / Alert fired / Recovered on recovery), then full-width Detectors / Parameters,
   plus a branded footer + footer icon. @mentions ride in the **top-level**
   message text so they notify. A custom `template` instead renders as a plain
   text-only attachment (color/title/ branding kept, no fields grid).
 - **Telegram** — default `parse_mode` is now **HTML**. The default message is
   structured and HTML-escaped: a colored status dot (red anomaly / green
   recovery / yellow no-data / blue error), a bold headline, the lead + rule, then
-  evidence in `<code>` (value/expected/quorum/severity/started → latest/detector/
+  evidence in `<code>` (value/expected/quorum/severity/began → latest/detector/
   params), an inline "Open dashboard" link, then mentions. This fixes the old
   Markdown mode raising "can't parse entities" on params JSON containing
   underscores (e.g. `window_size`). Custom templates are sent verbatim under the
@@ -212,7 +212,7 @@ leads with a colored **status circle** — 🔴 anomaly, 🟢 recovery, 🟡 no-
   old behavior.
 - **Email** — a branded HTML card (inline-CSS, table-based, Outlook-safe):
   colored accent + status pill, the metric, the lead + Rule chip, a 2-col stat
-  grid (value/expected/severity/quorum/started/latest), a monospace params box,
+  grid (value/expected/severity/quorum/anomaly began/latest reading; began/alert fired/recovered on recovery), a monospace params box,
   an optional "Open dashboard" button, and a footer. The plain-text body remains
   the multipart fallback.
 
@@ -226,15 +226,20 @@ identical everywhere.
 
 **Incident timing — "how long has this been going on".** Each default anomaly
 leads with `Anomalous for 2h 30m — 15 consecutive 10min intervals.` (metric
-interval + true streak length + wall-clock duration); Started/Latest bound the
-span. Recovery is symmetric (`Incident lasted …`, Started / Cleared). The true
+interval + true streak length + wall-clock duration); the **Anomaly began /
+Latest reading** fields bound the span. Labels are self-describing so the onset
+isn't misread as the alert-fire moment: **Anomaly began** is the resolved onset,
+**not** when the alert fired. Recovery shows the fuller **began → fired →
+recovered** timeline (`Incident lasted …`), where **Alert fired** =
+`onset + (consecutive_required − 1) × interval` (computed in `build_context`,
+exposed as `{fired_display}`, omitted when the run is capped). The true
 streak/onset is resolved only when an alert fires/clears (a bounded lookback over
 the detection history; a run older than the window shows `over …`), so the hot
 no-alert path stays cheap. Exposed to templates as `{anomaly_lead}` /
 `{recovery_lead}` / `{duration_display}` / `{interval_display}` /
-`{started_display}` / `{window_line}` — and `{consecutive_count}` now carries the
-*true* streak length. Custom templates and the plain-text fallbacks follow the
-same order.
+`{started_display}` / `{fired_display}` / `{window_line}` — and
+`{consecutive_count}` now carries the *true* streak length. Custom templates and
+the plain-text fallbacks follow the same order.
 
 ## Project label (multi-project channels)
 
@@ -294,7 +299,7 @@ referenced by path). Key variables:
 | `{direction}`, `{severity}` | observed values |
 | `{consecutive_count}` | **true** streak length (resolved at fire time, not capped at the rule) |
 | `{anomaly_lead}` / `{recovery_lead}` | ready-made "how long" lead sentence |
-| `{interval_display}` / `{duration_display}` / `{started_display}` / `{window_line}` | incident-timing bits (interval, duration, onset, `Started… \| Latest…` line) |
+| `{interval_display}` / `{duration_display}` / `{started_display}` / `{fired_display}` / `{window_line}` | incident-timing bits (interval, duration, onset, alert-fire moment, `Anomaly began… \| Latest reading…` line) |
 | `{status}` | `ANOMALY` / `RECOVERED` / `NO_DATA` / `ERROR` |
 | `{mentions}` / `{mentions_line}` | formatted mentions |
 | `{dashboard_url}` | raw `dashboard_url` (empty string when unset) |

{detectkit-0.34.0 → detectkit-0.35.0/detectkit.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: detectkit
-Version: 0.34.0
+Version: 0.35.0
 Summary: Metric monitoring with automatic anomaly detection
 Author: detectkit team
 License: MIT