: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
"""Facade for insight alerts.
Reads and writes other products need on the insight-alert model, in ids and plain values.
Destination configuration lives in `facade.destinations`, email in `facade.email`, the
lifecycle machine in `facade.lifecycle`, and scheduling math in `facade.scheduling`.
"""
import uuid
from collections.abc import Collection
from datetime import datetime, timedelta
from itertools import islice
from typing import Literal
from zoneinfo import ZoneInfo
from django.db import transaction
from django.db.models import Exists, OuterRef, Q
from django.utils import timezone
import structlog
from posthog.exceptions_capture import capture_exception
from posthog.models.activity_logging.activity_log import Change, Detail, log_activity
from posthog.models.activity_logging.model_activity import ActingUserContext
from posthog.models.team import Team
from posthog.models.user import User
from posthog.schema_enums import AlertState
from posthog.user_permissions import UserPermissions
from posthog.utils import relative_date_parse
from products.access_control.backend.facade.user_access_control import UserAccessControl
from products.alerts.backend.activity_logging import AlertConfigurationContext
from products.alerts.backend.facade import contracts
from products.alerts.backend.insight_alert_state_machine import apply_snooze
from products.alerts.backend.judge.contract import (
LLM_DETECTOR_PAUSED_ERROR_CODE,
LLM_DETECTOR_UNAVAILABLE_ERROR_CODE,
LLM_DETECTOR_UNAVAILABLE_MESSAGE,
MAX_CONCURRENT_MODEL_CALLS,
MAX_PROMPT_POINTS,
LLMDetectorError,
LLMDetectorMisconfiguredError,
LLMDetectorPausedError,
LLMDetectorUnavailableError,
)
from products.alerts.backend.judge.executor import LLM_EVALUATE_EXECUTOR
from products.alerts.backend.llm_detector_limits import (
LLMAlertRefusal,
LLMAlertWrite,
admit_llm_alert_write,
is_llm_detector_config,
llm_detector_access_error,
)
from products.alerts.backend.models.alert import (
METRICS_INSIGHT_QUERY_FILTER,
AlertCheck,
AlertConfiguration,
AlertSubscription,
)
from products.alerts_platform.backend.facade.contracts import InvalidPlatformAlertEdit
logger = structlog.get_logger(__name__)
SlackSnoozeOutcome = Literal["snoozed", "no_access", "disabled", "not_found", "invalid_until", "not_snoozable"]
# Mirrors the in-app SnoozeButton's DateFilter max — Slack's datetimepicker has no bounds of
# its own, so the cap has to live here.
SLACK_SNOOZE_MAX_DAYS = 31
def get_alert_team_id(alert_id: uuid.UUID) -> int | None:
"""The team an alert belongs to, or None if no such alert exists.
Lets callers outside this product (the Slack snooze-button handler) resolve an alert's team
— to find its workspace integration, and for region-ownership routing — without importing
the model directly.
"""
# Slack webhook: no team context available yet — this lookup only resolves the team so the
# caller can find the workspace integration; authorization is derived from the alert row in
# snooze_alert_from_slack below, not from this lookup.
# nosemgrep: idor-lookup-without-team
return AlertConfiguration.objects.filter(id=alert_id).values_list("team_id", flat=True).first()
def insight_ids_with_alerts(insight_ids: Collection[int]) -> set[int]:
"""Which of the given insights have at least one alert configured.
Lets callers outside this product treat "an alert points at this insight" as a signal that
something depends on it, without importing the model.
"""
# Caller-supplied ids that are already team-scoped by the caller's own query; this only maps
# ids to ids and returns no row data.
# nosemgrep: idor-lookup-without-team
return set(AlertConfiguration.objects.filter(insight_id__in=insight_ids).values_list("insight_id", flat=True))
def insight_ids_with_enabled_alerts(*, team_id: int, insight_ids: Collection[int]) -> set[int]:
"""Which of the team's given insights have at least one enabled alert, in one query."""
return set(
AlertConfiguration.objects.filter(team_id=team_id, insight_id__in=insight_ids, enabled=True).values_list(
"insight_id", flat=True
)
)
def enabled_alert_insight_ids(*, team_ids: Collection[int]) -> set[int]:
"""Insights of these teams with at least one enabled alert, in one query."""
if not team_ids:
return set()
return set(
AlertConfiguration.objects.filter(team_id__in=team_ids, enabled=True)
.values_list("insight_id", flat=True)
.distinct()
)
def delete_insight_alerts(insight_ids: Collection[int]) -> None:
"""Delete the alerts pointing at the given insights.
Call this inside the transaction that deletes or hides the insights themselves, so an
insight can never come back without its alerts. Rows go one at a time rather than through a
queryset delete, because a queryset delete never calls ``AlertConfiguration.delete()``, and
ModelActivityMixin hangs its per-row activity logging off that override.
"""
# Caller-supplied ids that are already team-scoped by the caller's own query.
# nosemgrep: idor-lookup-without-team
for alert in AlertConfiguration.objects.filter(insight_id__in=insight_ids):
alert.delete()
def snooze_alert_from_slack(
alert_id: uuid.UUID, *, user: User, duration: str | None = None, until: datetime | None = None
) -> SlackSnoozeOutcome:
"""Snooze an alert on behalf of a Slack snooze interaction.
Takes exactly one of ``duration`` (a preset token like ``"1d"``, resolved with the same
``relative_date_parse`` call the alerts API uses) or ``until`` (an absolute time from
Slack's datetimepicker, which must be in the future and at most ``SLACK_SNOOZE_MAX_DAYS``
out).
Owns all alert-side authorization and the mutation itself. `user` must already be confirmed
as a member of the alert's Slack-connected organization by the caller — the alert_id and
duration come from an untrusted Slack button value (user-editable hog function config), so
every access decision here is re-derived from the alert row, never taken on trust from the
caller.
"""
if (duration is None) == (until is None):
raise ValueError("Pass exactly one of duration or until")
try:
# Slack webhook: no team context, and alert_id/duration come from an untrusted Slack
# button value. Authorization is derived below from the alert row itself (project
# membership + insight viewer access), never taken on trust from the caller.
# nosemgrep: idor-lookup-without-team, idor-taint-user-input-to-model-get
alert = AlertConfiguration.objects.select_related("insight", "team").get(id=alert_id)
except AlertConfiguration.DoesNotExist:
return "not_found"
# Mirrors TeamMemberAccessPermission (posthog/permissions.py): a non-admin member with no
# explicit membership in a private project must be denied, even though they belong to the
# organization. effective_membership_level falls back to the plain org membership level when
# the organization doesn't have ACCESS_CONTROL, so this never false-denies on non-EE orgs.
if UserPermissions(user).team(alert.team).effective_membership_level is None:
logger.warning("alert_snooze_no_project_membership", alert_id=str(alert_id), user_id=user.id)
return "no_access"
# Project membership doesn't imply access to every insight in it — mirrors
# _require_insight_viewer_access, the same check the alerts API itself uses.
if not UserAccessControl(user, team=alert.team).check_access_level_for_object(alert.insight, "viewer"):
logger.warning("alert_snooze_no_insight_access", alert_id=str(alert_id), user_id=user.id)
return "no_access"
if not alert.enabled:
# Fast path only — not the authoritative check. A concurrent disable between here and
# the row-locked re-check below must still be caught, so this just avoids taking a lock
# for the common case.
return "disabled"
if duration is not None:
# always store snoozed_until as UTC time, as we look at current UTC time to check when to
# run alerts — same call the alerts API uses so "1d" means the same thing everywhere.
snoozed_until = relative_date_parse(duration, ZoneInfo("UTC"), increase=True, always_truncate=True)
else:
assert until is not None
now = timezone.now()
if until <= now or until > now + timedelta(days=SLACK_SNOOZE_MAX_DAYS):
return "invalid_until"
snoozed_until = until.astimezone(ZoneInfo("UTC"))
with transaction.atomic():
try:
# Authoritative re-check under a row lock: without this, a concurrent disable
# between the fast-path check above and this mutation would still persist
# enabled=False alongside state=SNOOZED — a state the alert should never be in.
# nosemgrep: idor-lookup-without-team, idor-taint-user-input-to-model-get
locked_alert = AlertConfiguration.objects.select_for_update().get(id=alert_id)
except AlertConfiguration.DoesNotExist:
return "not_found"
if not locked_alert.enabled:
return "disabled"
with ActingUserContext(user):
state_fields = apply_snooze(locked_alert)
locked_alert.snoozed_until = snoozed_until
locked_alert.save(update_fields=[*state_fields, "snoozed_until"])
if locked_alert.platform_owned:
# The platform's copy mutes delivery, so it takes the snooze under the same lock.
from products.alerts.backend.platform_ownership import ( # noqa: PLC0415 - platform_ownership reaches this module back
on_updated,
)
try:
on_updated(locked_alert, snooze_changed=True)
except (contracts.PlatformCannotOwn, InvalidPlatformAlertEdit) as error:
# Neither row takes the snooze, so the alert does not mute on one stack only.
capture_exception(error, {"alert_id": str(alert_id)})
transaction.set_rollback(True)
return "not_snoozable"
AlertCheck.objects.create(
alert_configuration=locked_alert,
calculated_value=None,
condition=locked_alert.condition,
targets_notified={},
state=locked_alert.state,
error=None,
)
return "snoozed"
FIRING_ALERT_CANDIDATES = 200
def list_firing_alerts_created_by(
team: Team, user: User, *, include_metrics_insights: bool, limit: int
) -> list[contracts.FiringAlert]:
alerts = AlertConfiguration.objects.filter(
team_id=team.id,
enabled=True,
state=AlertState.FIRING,
created_by_id=user.id,
insight__deleted=False,
).filter(Q(snoozed_until__isnull=True) | Q(snoozed_until__lt=timezone.now()))
if not include_metrics_insights:
alerts = alerts.exclude(id__in=alerts.filter(METRICS_INSIGHT_QUERY_FILTER).values("id"))
access = UserAccessControl(user, team=team)
candidates = alerts.select_related("insight").order_by("-created_at")[:FIRING_ALERT_CANDIDATES]
viewable = (alert for alert in candidates if access.check_access_level_for_object(alert.insight, "viewer"))
return [
contracts.FiringAlert(
id=alert.id,
name=alert.name,
insight_name=alert.insight.name or alert.insight.derived_name,
insight_short_id=alert.insight.short_id,
)
for alert in islice(viewable, limit)
]
WATCHED_ROWS_PER_INSIGHT = 4
def insight_short_ids_watched_by(*, team_id: int, user_id: int, limit: int) -> list[str]:
"""Short ids of insights with an enabled alert that the user created or subscribes to, newest alert first."""
follows = AlertSubscription.objects.filter(alert_configuration=OuterRef("pk"), user_id=user_id, subscribed=True)
rows = (
AlertConfiguration.objects.filter(team_id=team_id, enabled=True, insight__deleted=False)
.filter(Q(created_by_id=user_id) | Exists(follows))
.order_by("-created_at")
.values_list("insight__short_id", flat=True)[: limit * WATCHED_ROWS_PER_INSIGHT]
)
return list(dict.fromkeys(rows))[:limit]
def assign_alert_owner(*, team_id: int, alert_id: uuid.UUID, user: User, was_impersonated: bool) -> None:
"""Make `user` the owner of the alert and record the takeover in the activity log.
`created_by` is excluded from the save diff, so the takeover gets its own activity.
"""
alert = AlertConfiguration.objects.select_related("insight", "created_by").get(team_id=team_id, id=alert_id)
previous_owner = alert.created_by
alert.created_by = user
alert.save(update_fields=["created_by"])
log_activity(
organization_id=alert.team.organization_id,
team_id=alert.team_id,
user=user,
was_impersonated=was_impersonated,
item_id=alert.id,
scope="AlertConfiguration",
activity="took_ownership",
detail=Detail(
name=alert.name or f"Alert for {alert.insight.name}",
changes=[
Change(
type="AlertConfiguration",
action="changed",
field="created_by",
before={"id": previous_owner.id, "email": previous_owner.email} if previous_owner else None,
after={"id": user.id, "email": user.email},
)
],
context=AlertConfigurationContext(
insight_id=alert.insight_id,
insight_short_id=alert.insight.short_id,
insight_name=alert.insight.name,
),
),
)
__all__ = [
"LLM_DETECTOR_PAUSED_ERROR_CODE",
"LLM_DETECTOR_UNAVAILABLE_ERROR_CODE",
"LLM_DETECTOR_UNAVAILABLE_MESSAGE",
"LLM_EVALUATE_EXECUTOR",
"MAX_CONCURRENT_MODEL_CALLS",
"MAX_PROMPT_POINTS",
"LLMAlertRefusal",
"LLMAlertWrite",
"LLMDetectorError",
"LLMDetectorMisconfiguredError",
"LLMDetectorPausedError",
"LLMDetectorUnavailableError",
"admit_llm_alert_write",
"assign_alert_owner",
"is_llm_detector_config",
"llm_detector_access_error",
]