Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

6.3 KB
Raw Blame
"""Single source of truth for LogsAlertConfiguration state transitions.

Any write to `LogsAlertConfiguration.state` or `LogsAlertConfiguration.consecutive_failures`
MUST originate here — the check-driven path goes through `evaluate_alert_check`, the
control-plane path goes through one of the `apply_*` helpers, and every caller applies
the resulting outcome via `apply_outcome`, which is the only function in the codebase
that mutates those two fields.

The semgrep rule at `.semgrep/rules/security/alert-state-must-go-through-state-machine.yaml`
enforces this invariant in CI.

The decision logic itself lives in `products/alerts/backend/facade/lifecycle.py`
(configured here with `LOGS_ALERT_POLICY`); this module owns the logs-shaped inputs
(`AlertSnapshot`, `CheckResult`) and the model mutation (`apply_outcome`).
"""

from __future__ import annotations

from dataclasses import dataclass
from datetime import datetime, timedelta
from enum import StrEnum
from typing import TYPE_CHECKING

from products.alerts_platform.backend.facade.contracts import IncidentAction
from products.alerts_platform.backend.facade.lifecycle import (
    FIRING_STATES,
    LOGS_ALERT_POLICY,
    MAX_CONSECUTIVE_FAILURES,
    AlertCheckOutcome,
    AlertSnapshot as SharedAlertSnapshot,
    AlertState,
    CheckInput,
    ControlPlaneOutcome,
    InvalidTransition,
    NotificationAction,
    Outcome,
    apply_disable,
    apply_enable,
    apply_snooze,
    apply_threshold_change,
    apply_unsnooze,
    apply_user_reset,
    decide_incident_action,
    evaluate_alert_check as shared_evaluate_alert_check,
)

if TYPE_CHECKING:
    from products.logs.backend.models import LogsAlertConfiguration, LogsAlertEvent

__all__ = [
    "MAX_CONSECUTIVE_FAILURES",
    "AlertCheckOutcome",
    "AlertSnapshot",
    "AlertState",
    "FIRING_STATES",
    "CheckResult",
    "ControlPlaneOutcome",
    "IncidentCloseReason",
    "IncidentEdge",
    "InvalidTransition",
    "NotificationAction",
    "Outcome",
    "apply_disable",
    "apply_enable",
    "apply_outcome",
    "apply_snooze",
    "apply_threshold_change",
    "apply_unsnooze",
    "apply_user_reset",
    "evaluate_alert_check",
    "incident_edge",
]


@dataclass(frozen=True)
class CheckResult:
    result_count: int | None
    threshold_breached: bool
    error_message: str | None = None
    query_duration_ms: int | None = None
    is_transient_error: bool = False


@dataclass(frozen=True)
class AlertSnapshot:
    state: AlertState
    evaluation_periods: int
    datapoints_to_alarm: int
    cooldown_minutes: int
    last_notified_at: datetime | None
    snooze_until: datetime | None
    consecutive_failures: int
    recent_events_breached: tuple[bool, ...]


class IncidentEdge(StrEnum):
    OPENED = "opened"
    CLOSED = "closed"


class IncidentCloseReason(StrEnum):
    RESOLVED = "resolved"
    BROKEN = "broken"
    DISABLED = "disabled"
    SNOOZED = "snoozed"
    CONFIG_CHANGED = "config_changed"
    DELETED = "deleted"


def incident_edge(state_before: str, new_state: str) -> IncidentEdge | None:
    """Whether a transition starts or ends a firing, by the shared rule the alerts platform uses."""
    action = decide_incident_action(AlertState(state_before), AlertState(new_state), policy=LOGS_ALERT_POLICY)
    if action is None:
        return None
    return IncidentEdge.OPENED if action == IncidentAction.TRIGGER else IncidentEdge.CLOSED


def evaluate_alert_check(
    snapshot: AlertSnapshot,
    check: CheckResult,
    now: datetime,
) -> AlertCheckOutcome:
    """Implements the RFC state table: N-of-M sliding-window trigger
    (CloudWatch-style) for firing, immediate resolution on the first OK
    check, and cooldown suppression.
    """
    return shared_evaluate_alert_check(
        SharedAlertSnapshot(
            state=snapshot.state,
            cooldown=timedelta(minutes=snapshot.cooldown_minutes),
            last_notified_at=snapshot.last_notified_at,
            snooze_until=snapshot.snooze_until,
            consecutive_failures=snapshot.consecutive_failures,
            evaluation_periods=snapshot.evaluation_periods,
            datapoints_to_alarm=snapshot.datapoints_to_alarm,
            recent_events_breached=snapshot.recent_events_breached,
        ),
        CheckInput(
            threshold_breached=check.threshold_breached,
            error_message=check.error_message,
            is_transient_error=check.is_transient_error,
        ),
        now,
        policy=LOGS_ALERT_POLICY,
    )


def apply_outcome(
    alert: LogsAlertConfiguration,
    outcome: Outcome,
    *,
    kind: LogsAlertEvent.Kind | None = None,
) -> list[str]:
    """Mutates `alert.state` and `alert.consecutive_failures` from an outcome.
    Returns modified field names for `save(update_fields=...)`.

    If `kind` is provided, writes a `LogsAlertEvent` audit row — even when
    state_before == state_after, because the caller has already decided the action
    is audit-worthy (e.g. enabling an already-NOT_FIRING alert). Worker CHECK rows
    are written by the temporal activity, not here.
    """
    state_before = alert.state
    alert.state = outcome.new_state.value
    alert.consecutive_failures = outcome.consecutive_failures

    if kind is not None:
        from products.logs.backend.models import LogsAlertEvent

        LogsAlertEvent.objects.create(
            alert=alert,
            kind=kind,
            threshold_breached=False,
            state_before=state_before,
            state_after=outcome.new_state.value,
        )

    return ["state", "consecutive_failures"]


def apply_enabled(alert: LogsAlertConfiguration, enabled: bool, *, now: datetime) -> list[str]:
    """Turns an alert on or off with the transition and audit row the logs API writes for it.
    Returns modified field names for `save(update_fields=...)`, none when `enabled` is unchanged."""
    from products.logs.backend.models import LogsAlertEvent

    if alert.enabled == enabled:
        return []
    snapshot = alert.to_snapshot()
    if enabled:
        update_fields = apply_outcome(alert, apply_enable(snapshot), kind=LogsAlertEvent.Kind.ENABLE)
        if alert.first_enabled_at is None:
            alert.first_enabled_at = now
            update_fields.append("first_enabled_at")
    else:
        update_fields = apply_outcome(alert, apply_disable(snapshot), kind=LogsAlertEvent.Kind.DISABLE)
    alert.enabled = enabled
    return [*update_fields, "enabled"]