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.

25.8 KB
Raw Blame
from __future__ import annotations

from datetime import UTC, datetime, timedelta
from typing import TYPE_CHECKING, Any

from django.core.exceptions import ValidationError
from django.db import models

if TYPE_CHECKING:
    from posthog.event_usage import AnalyticsProps
    from posthog.models.organization import Organization
    from posthog.models.user import User

import pydantic

from posthog.constants import AvailableFeature
from posthog.models.activity_logging.model_activity import ModelActivityMixin
from posthog.models.utils import CreatedMetaFields, UUIDTModel
from posthog.schema_enums import AlertCalculationInterval, AlertState

from products.alerts_platform.backend.facade.enums import PlatformAlertOwner

ALERT_STATE_CHOICES = [
    (AlertState.FIRING, AlertState.FIRING),
    (AlertState.NOT_FIRING, AlertState.NOT_FIRING),
    (AlertState.ERRORED, AlertState.ERRORED),
    (AlertState.SNOOZED, AlertState.SNOOZED),
]

# Matches insights whose (bare or one-level-wrapped) query is a MetricsQuery — the shapes the
# product persists today. Used to hide metric alert data from tokens lacking the metrics scope.
METRICS_INSIGHT_QUERY_FILTER = models.Q(insight__query__kind="MetricsQuery") | models.Q(
    insight__query__source__kind="MetricsQuery"
)


class InvestigationStatus(models.TextChoices):
    PENDING = "pending", "pending"
    RUNNING = "running", "running"
    DONE = "done", "done"
    FAILED = "failed", "failed"
    SKIPPED = "skipped", "skipped"


class InvestigationVerdict(models.TextChoices):
    """The investigation agent's call on whether the firing alert was real.

    We keep this independent from InvestigationStatus so that status tracks the
    pipeline (did it run?) while verdict tracks the conclusion (was it real?).
    Future work may let users override this field manually.
    """

    TRUE_POSITIVE = "true_positive", "true_positive"
    FALSE_POSITIVE = "false_positive", "false_positive"
    INCONCLUSIVE = "inconclusive", "inconclusive"


def derive_detector_event_fields(detector_config: dict | None) -> dict:
    """Shared derivation of alert_mode/detector_type/ensemble_operator from a detector config.

    Used by both `alert created`/`alert updated` user-action events and the
    `$insight_alert_firing` internal event so the taxonomy stays in one place.
    """
    detector_config = detector_config or {}
    detector_type = detector_config.get("type")
    return {
        "alert_mode": "detector" if detector_type else "threshold",
        "detector_type": detector_type,
        "ensemble_operator": detector_config.get("operator") if detector_type == "ensemble" else None,
    }


# TODO: Enable `@deprecated` once we move to Python 3.13
# @deprecated("AlertConfiguration should be used instead.")
class Alert(models.Model):
    team = models.ForeignKey("posthog.Team", on_delete=models.CASCADE, related_name="+")
    insight = models.ForeignKey("product_analytics.Insight", on_delete=models.CASCADE, related_name="+")

    name = models.CharField(max_length=100)
    target_value = models.TextField()
    anomaly_condition = models.JSONField(default=dict)

    class Meta:
        db_table = "posthog_alert"


class Threshold(ModelActivityMixin, CreatedMetaFields, UUIDTModel):
    """
    Threshold holds the configuration for a threshold. This can either be attached to an alert, or used as a standalone
    object for other purposes.
    """

    team = models.ForeignKey("posthog.Team", on_delete=models.CASCADE, related_name="+")
    insight = models.ForeignKey("product_analytics.Insight", on_delete=models.CASCADE, related_name="+")

    name = models.CharField(max_length=255, blank=True)
    configuration = models.JSONField(default=dict)

    class Meta:
        db_table = "posthog_threshold"

    def clean(self) -> None:
        try:
            # Deferred: posthog.schema (the pydantic models) stays off django.setup(),
            # where this model loads in every process.
            from posthog.schema import InsightThreshold  # noqa: PLC0415

            config = InsightThreshold.model_validate(self.configuration)
        except pydantic.ValidationError as e:
            raise ValidationError(f"Invalid threshold configuration: {e}")

        if not config or not config.bounds:
            return
        if config.bounds.lower is not None and config.bounds.upper is not None:
            if config.bounds.lower > config.bounds.upper:
                raise ValidationError("Lower threshold must be less than upper threshold")


class AlertConfiguration(ModelActivityMixin, CreatedMetaFields, UUIDTModel):
    ALERTS_ALLOWED_ON_FREE_TIER = 5

    team = models.ForeignKey("posthog.Team", on_delete=models.CASCADE)
    insight = models.ForeignKey("product_analytics.Insight", on_delete=models.CASCADE)

    name = models.CharField(max_length=255, blank=True)
    subscribed_users = models.ManyToManyField(
        "posthog.User",
        through="alerts.AlertSubscription",
        through_fields=("alert_configuration", "user"),
        related_name="alert_configurations",
    )

    # insight specific config for the alert
    config = models.JSONField(default=dict, null=True, blank=True)
    evaluation_delay_intervals = models.PositiveSmallIntegerField(default=0, db_default=0)

    # how often to recalculate the alert
    CALCULATION_INTERVAL_CHOICES = [
        (AlertCalculationInterval.REAL_TIME, AlertCalculationInterval.REAL_TIME.value),
        (AlertCalculationInterval.EVERY_15_MINUTES, AlertCalculationInterval.EVERY_15_MINUTES.value),
        (AlertCalculationInterval.HOURLY, AlertCalculationInterval.HOURLY.value),
        (AlertCalculationInterval.DAILY, AlertCalculationInterval.DAILY.value),
        (AlertCalculationInterval.WEEKLY, AlertCalculationInterval.WEEKLY.value),
        (AlertCalculationInterval.MONTHLY, AlertCalculationInterval.MONTHLY.value),
    ]
    calculation_interval = models.CharField(
        max_length=20,
        choices=CALCULATION_INTERVAL_CHOICES,
        default=AlertCalculationInterval.DAILY.value,
        null=True,
        blank=True,
    )

    # The threshold to evaluate the alert against. If null, the alert must have other conditions to trigger.
    threshold = models.ForeignKey(Threshold, on_delete=models.CASCADE, null=True, blank=True)
    condition = models.JSONField(default=dict)

    # Detector-based anomaly detection configuration (alternative to threshold)
    detector_config = models.JSONField(null=True, blank=True)

    state = models.CharField(max_length=10, choices=ALERT_STATE_CHOICES, default=AlertState.NOT_FIRING.value)
    enabled = models.BooleanField(default=True)

    last_notified_at = models.DateTimeField(null=True, blank=True)
    last_checked_at = models.DateTimeField(null=True, blank=True)
    # UTC time for when next alert check is due. Null only before the first
    # check, when created_at is the scheduler's due-age lower bound.
    next_check_at = models.DateTimeField(null=True, blank=True)
    # UTC time until when we shouldn't check alert/notify user
    snoozed_until = models.DateTimeField(null=True, blank=True)

    skip_weekend = models.BooleanField(null=True, blank=True, default=False)

    schedule_restriction = models.JSONField(null=True, blank=True, default=None)
    schedule_start_time = models.CharField(max_length=5, null=True, blank=True, default=None)

    # When enabled, an investigation agent runs on each firing check, up to three per
    # firing episode, and writes its findings to a linked Notebook. Only effective for
    # detector-based (anomaly) alerts. See posthog/temporal/alerts/investigation.py for
    # the trigger logic.
    investigation_agent_enabled = models.BooleanField(default=False)

    # When enabled (and investigation_agent_enabled is on), the episode's first fire is
    # held until the investigation agent produces a verdict, and suppressed if the
    # verdict is false_positive. Later fires of the episode notify without waiting. A
    # safety-net Temporal workflow force-notifies after a grace period if the
    # investigation stalls, so users can never silently miss a real fire.
    # See posthog/temporal/alerts/workflows.py (RunInvestigationSafetyNetWorkflow).
    investigation_gates_notifications = models.BooleanField(default=False)

    # What to do with an "inconclusive" verdict when notifications are gated.
    # Default is notify — safest for anomaly alerts where the agent not being sure
    # is itself informative.
    INVESTIGATION_INCONCLUSIVE_ACTION_CHOICES = [
        ("notify", "Notify"),
        ("suppress", "Suppress"),
    ]
    investigation_inconclusive_action = models.CharField(
        max_length=10,
        choices=INVESTIGATION_INCONCLUSIVE_ACTION_CHOICES,
        default="notify",
    )

    # Which stack evaluates and delivers this alert. The platform's copy records the same owner,
    # and only the cutover and rollback commands write the two. After a cutover the insight stack
    # keeps evaluating the alert for a shadow window from `owner_changed_at`, and sends nothing.
    owner = models.CharField(
        max_length=16,
        choices=PlatformAlertOwner.choices,
        default=PlatformAlertOwner.SOURCE.value,
        db_default=PlatformAlertOwner.SOURCE.value,
    )
    owner_changed_at = models.DateTimeField(null=True, blank=True)

    class Meta:
        db_table = "posthog_alertconfiguration"

    def __str__(self) -> str:
        return f"{self.name} (Team: {self.team})"

    def internal_event_properties(self, *, state: str, last_checked_at: datetime | None) -> dict[str, Any]:
        """The properties every `$insight_alert_firing` carries, from the insight stack or the platform."""
        return {
            "alert_id": str(self.id),
            "alert_name": self.name,
            "project_name": self.team.name,
            "insight_name": self.insight.name,
            "insight_id": self.insight.short_id,
            "state": state,
            "last_checked_at": last_checked_at.isoformat() if last_checked_at else None,
            **derive_detector_event_fields(self.detector_config),
        }

    @property
    def platform_owned(self) -> bool:
        """The platform evaluates and delivers this alert. The insight stack may still evaluate it to
        compare, but it sends nothing for it."""
        return self.owner == PlatformAlertOwner.PLATFORM

    @property
    def platform_owned_since(self) -> datetime | None:
        """When the platform took this alert over, or None while the insight stack owns it.

        The alert's own checks before then are its history. Its own checks after then are the shadow's,
        which sent nothing, so the platform's checks replace them.
        """
        return self.owner_changed_at if self.platform_owned else None

    @property
    def is_high_frequency_interval(self) -> bool:
        # Real-time counts as high frequency so its checks always run fresh ClickHouse
        # queries (CALCULATE_BLOCKING_ALWAYS) instead of reading a possibly stale cache.
        return self.calculation_interval in (
            AlertCalculationInterval.EVERY_15_MINUTES,
            AlertCalculationInterval.REAL_TIME,
        )

    def get_subscribed_users_emails(self) -> list[str]:
        return list(
            self.subscribed_users.filter(organization_membership__organization=self.team.organization).values_list(
                "email", flat=True
            )
        )

    def _get_event_properties(self) -> dict:
        detector_config = self.detector_config or {}
        detector_type = detector_config.get("type")

        ensemble_detector_types: list[str] | None = None
        has_preprocessing = False

        if detector_type == "ensemble":
            sub_detectors = detector_config.get("detectors") or []
            ensemble_detector_types = [sub.get("type") for sub in sub_detectors if sub.get("type")]
            has_preprocessing = any(sub.get("preprocessing") for sub in sub_detectors)
        elif detector_type:
            has_preprocessing = bool(detector_config.get("preprocessing"))

        schedule_restriction = self.schedule_restriction
        has_schedule_restriction = False
        blocked_window_count: int | None = None
        if isinstance(schedule_restriction, dict):
            windows = schedule_restriction.get("blocked_windows")
            if isinstance(windows, list):
                blocked_window_count = len(windows)
                has_schedule_restriction = blocked_window_count > 0

        threshold_configuration: dict = {}
        if self.threshold and isinstance(self.threshold.configuration, dict):
            threshold_configuration = self.threshold.configuration
        threshold_bounds = threshold_configuration.get("bounds") or {}
        has_threshold = self.threshold is not None
        threshold_type = threshold_configuration.get("type") if has_threshold else None
        has_lower_bound = threshold_bounds.get("lower") is not None if has_threshold else False
        has_upper_bound = threshold_bounds.get("upper") is not None if has_threshold else False

        alert_config = self.config if isinstance(self.config, dict) else {}
        is_hogql_config = alert_config.get("type") == "HogQLAlertConfig"

        subscribed_users_count: int | None = None
        if self.pk is not None:
            subscribed_users_count = self.subscribed_users.count()

        return {
            "alert_id": self.id,
            "alert_name": self.name,
            "condition_type": self.condition.get("type") if self.condition else None,
            "calculation_interval": self.calculation_interval,
            "is_high_frequency_interval": self.is_high_frequency_interval,
            "enabled": self.enabled,
            "investigation_agent_enabled": self.investigation_agent_enabled,
            "skip_weekend": bool(self.skip_weekend),
            "has_schedule_restriction": has_schedule_restriction,
            "has_threshold": has_threshold,
            "threshold_type": threshold_type,
            "has_lower_bound": has_lower_bound,
            "has_upper_bound": has_upper_bound,
            "config_type": alert_config.get("type"),
            "trends_series_index": alert_config.get("series_index"),
            "trends_check_ongoing_interval": alert_config.get("check_ongoing_interval"),
            "evaluation_delay_intervals": self.evaluation_delay_intervals,
            "hogql_evaluation": (alert_config.get("evaluation") or "last_row") if is_hogql_config else None,
            "hogql_has_explicit_column": bool(alert_config.get("column")) if is_hogql_config else None,
            "hogql_has_label_column": bool(alert_config.get("label_column")) if is_hogql_config else None,
            "subscribed_users_count": subscribed_users_count,
            **derive_detector_event_fields(detector_config),
            "ensemble_detector_types": ensemble_detector_types,
            "has_preprocessing": has_preprocessing,
            "schedule_restriction_blocked_window_count": blocked_window_count,
        }

    def report_created(self, user: User, analytics_props: AnalyticsProps | None = None) -> None:
        from posthog.event_usage import report_user_action

        report_user_action(user, "alert created", self._get_event_properties(), analytics_props=analytics_props)

    def report_updated(self, user: User, analytics_props: AnalyticsProps | None = None) -> None:
        from posthog.event_usage import report_user_action

        report_user_action(user, "alert updated", self._get_event_properties(), analytics_props=analytics_props)

    @classmethod
    def check_alert_limit(cls, team_id: int, organization: Organization) -> str | None:
        """Return an error message if the team has reached its alert limit, else None."""
        alerts_feature = organization.get_available_feature(AvailableFeature.ALERTS)

        if alerts_feature:
            allowed = alerts_feature.get("limit")
            # If allowed is None then the user is allowed unlimited alerts
            if allowed is not None and cls._counted(team_id) >= allowed:
                return f"Your team has reached the limit of {allowed} alerts on your plan."
        else:
            # If the org doesn't have alerts feature, limit to that on free tier
            if cls._counted(team_id) >= cls.ALERTS_ALLOWED_ON_FREE_TIER:
                return f"Your plan is limited to {cls.ALERTS_ALLOWED_ON_FREE_TIER} alerts."

        return None

    @classmethod
    def _counted(cls, team_id: int, *, active_real_time: bool = False, exclude_id: str | None = None) -> int:
        """The team's insight alerts: each insight row, and each platform alert with no insight row."""
        # Deferred: the platform's read logic stays off django.setup(), where this model loads in every process.
        from products.alerts_platform.backend.facade.api import count_configurations  # noqa: PLC0415
        from products.alerts_platform.backend.facade.contracts import SourceKind  # noqa: PLC0415
        from products.alerts_platform.backend.facade.scheduling import REAL_TIME_CADENCE_MINUTES  # noqa: PLC0415

        rows = cls.objects.filter(team_id=team_id)
        if active_real_time:
            rows = rows.filter(calculation_interval=AlertCalculationInterval.REAL_TIME, enabled=True)
        if exclude_id:
            rows = rows.exclude(pk=exclude_id)
        native = count_configurations(
            team_id=team_id,
            source_kind=SourceKind.INSIGHT,
            native_only=True,
            enabled_only=active_real_time,
            check_interval_minutes=REAL_TIME_CADENCE_MINUTES if active_real_time else None,
        )
        return rows.count() + native

    @classmethod
    def supports_high_frequency_intervals(cls, organization: Organization) -> bool:
        return organization.is_feature_available(AvailableFeature.HIGH_FREQUENCY_ALERTS)

    @classmethod
    def every_15_minutes_interval_validation_error(
        cls,
        *,
        calculation_interval: str | AlertCalculationInterval | None,
        organization: Organization,
    ) -> str | None:
        if calculation_interval != AlertCalculationInterval.EVERY_15_MINUTES:
            return None
        if not cls.supports_high_frequency_intervals(organization):
            return "15-minute alert intervals require a Boost, Scale, or Enterprise platform add-on."
        return None

    @classmethod
    def real_time_interval_validation_error(
        cls,
        *,
        calculation_interval: str | AlertCalculationInterval | None,
        organization: Organization,
    ) -> str | None:
        if calculation_interval != AlertCalculationInterval.REAL_TIME:
            return None
        if not organization.is_feature_available(AvailableFeature.REAL_TIME_ALERTS):
            return "Real-time alert intervals require a Scale or Enterprise plan."
        return None

    @classmethod
    def interval_entitlement_error(
        cls,
        *,
        calculation_interval: str | AlertCalculationInterval | None,
        organization: Organization,
    ) -> str | None:
        """Entitlement gate for any plan-restricted interval — the single entry point for
        write paths and evaluation-time downgrade checks. Each underlying check returns None
        unless the interval matches, so at most one can produce an error."""
        return cls.real_time_interval_validation_error(
            calculation_interval=calculation_interval, organization=organization
        ) or cls.every_15_minutes_interval_validation_error(
            calculation_interval=calculation_interval, organization=organization
        )

    @classmethod
    def check_real_time_alert_limit(
        cls, team_id: int, organization: Organization, *, exclude_id: str | None = None
    ) -> str | None:
        """Return an error message if the team has reached its real-time alert limit, else None.

        Unlike check_alert_limit (which counts every alert against the ALERTS feature), this
        counts only real-time alerts against the REAL_TIME_ALERTS feature's limit. Orgs without
        the feature are already blocked by real_time_interval_validation_error.
        """
        feature = organization.get_available_feature(AvailableFeature.REAL_TIME_ALERTS)
        if not feature:
            return None

        allowed = feature.get("limit")
        if allowed is None:
            return None

        existing_count = cls._counted(team_id, active_real_time=True, exclude_id=exclude_id)
        if existing_count >= allowed:
            return f"Your team has reached the limit of {allowed} real-time alerts on your plan."
        return None

    @classmethod
    def real_time_alert_validation_error(
        cls,
        *,
        team_id: int,
        organization: Organization,
        calculation_interval: str | AlertCalculationInterval | None,
        enabled: bool,
        existing: AlertConfiguration | None = None,
    ) -> str | None:
        """Validate the active real-time limit for a create/update that would leave an alert
        in the given real-time state.

        Purely the limit check — callers gate the entitlement first via
        interval_entitlement_error. The limit only applies when the change increases the
        active real-time count — an alert that already was an enabled real_time alert
        doesn't re-count against it.
        """
        if calculation_interval != AlertCalculationInterval.REAL_TIME:
            return None
        if not enabled:
            return None
        already_active_real_time = (
            existing is not None
            and existing.calculation_interval == AlertCalculationInterval.REAL_TIME
            and existing.enabled
        )
        if already_active_real_time:
            return None
        return cls.check_real_time_alert_limit(team_id, organization, exclude_id=str(existing.pk) if existing else None)


class AlertSubscription(ModelActivityMixin, CreatedMetaFields, UUIDTModel):
    user = models.ForeignKey(
        "posthog.User",
        on_delete=models.CASCADE,
        limit_choices_to={
            "is_active": True,
            "organization_id": models.OuterRef("alert_configuration__team__organization_id"),
        },
        related_name="alert_subscriptions",
    )
    alert_configuration = models.ForeignKey(AlertConfiguration, on_delete=models.CASCADE)
    subscribed = models.BooleanField(default=True)

    def __str__(self) -> str:
        return f"AlertSubscription for {self.alert_configuration.name} by {self.user.email}"

    class Meta:
        unique_together = ["user", "alert_configuration"]
        db_table = "posthog_alertsubscription"


class AlertCheck(UUIDTModel):
    alert_configuration = models.ForeignKey(AlertConfiguration, on_delete=models.CASCADE)
    created_at = models.DateTimeField(auto_now_add=True)
    calculated_value = models.FloatField(null=True, blank=True)
    condition = models.JSONField(default=dict)  # Snapshot of the condition at the time of the check
    # {} = no delivery. For legacy reasons "users" holds email addresses only;
    # "destinations" holds the other channels' receipts (see AlertDelivery).
    targets_notified = models.JSONField(default=dict)
    error = models.JSONField(null=True, blank=True)

    state = models.CharField(max_length=10, choices=ALERT_STATE_CHOICES, default=AlertState.NOT_FIRING.value)

    # Detector-based anomaly detection results
    anomaly_scores = models.JSONField(null=True, blank=True)  # Scores for each data point
    triggered_points = models.JSONField(null=True, blank=True)  # Indices of detected anomalies
    triggered_dates = models.JSONField(null=True, blank=True)  # Dates for chart alignment
    interval = models.CharField(max_length=10, null=True, blank=True)  # Insight interval when check was created
    triggered_metadata = models.JSONField(
        null=True, blank=True
    )  # Additional trigger context (e.g. series_index, breakdown_value)

    # Investigation agent linkage — populated when the alert transitions to FIRING and
    # investigation_agent_enabled is true. Lives on the check record so the notebook is
    # surfaced inline with the specific firing event it investigated.
    investigation_status = models.CharField(max_length=10, choices=InvestigationStatus.choices, null=True, blank=True)
    investigation_verdict = models.CharField(max_length=20, choices=InvestigationVerdict.choices, null=True, blank=True)
    investigation_notebook = models.ForeignKey(
        "notebooks.Notebook",
        on_delete=models.SET_NULL,
        null=True,
        blank=True,
        related_name="+",
    )
    # Short plain-text summary the agent emits. Safe to show inline in lists, emails,
    # and Slack follow-ups so a user can decide whether to click into the notebook.
    investigation_summary = models.TextField(null=True, blank=True)
    investigation_error = models.JSONField(null=True, blank=True)

    # Populated when a notification is dispatched for this check. Lets the gating
    # logic be idempotent across retries and is the audit trail for "when did the
    # user actually get pinged?" when the investigation agent is gating notifications.
    notification_sent_at = models.DateTimeField(null=True, blank=True)
    # True when the investigation agent concluded false_positive (or inconclusive
    # with suppress policy) and we skipped dispatching the notification. Surfaced
    # in the UI so users can audit which fires the agent swallowed.
    notification_suppressed_by_agent = models.BooleanField(default=False)

    class Meta:
        db_table = "posthog_alertcheck"

    def __str__(self) -> str:
        return f"AlertCheck for {self.alert_configuration.name} at {self.created_at}"

    @property
    def has_delivery_receipts(self) -> bool:
        """True when this row was written by record_alert_delivery (which always sets
        the "destinations" key); legacy rows only carry configured recipients."""
        return "destinations" in (self.targets_notified or {})

    RETENTION = timedelta(days=14)

    @classmethod
    def clean_up_old_checks(cls) -> int:
        oldest_allowed_date = datetime.now(UTC) - cls.RETENTION
        rows_count, _ = cls.objects.filter(created_at__lt=oldest_allowed_date).delete()
        return rows_count