: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.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
"""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"]