: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
feat(alerts): word native insight alert messages the insight way (#120592)
Jimmy Zhu9caeedd8ead1
diff --git a/posthog/templates/email/alert_platform_notification.html b/posthog/templates/email/alert_platform_notification.htmlindex 84411a5f64a3..74723af50799 100644--- a/posthog/templates/email/alert_platform_notification.html+++ b/posthog/templates/email/alert_platform_notification.html@@ -7,5 +7,15 @@{% endfor %}</ul>{% endif %}+{% if context %}+ <p>+ {% for line in context %}{{ line }}{% if not forloop.last %}<br />{% endif %}{% endfor %}+ </p>+{% endif %}+{% if links %}+ <p>+ {% for link in links %}<a href="{{ link.url }}">{{ link.label }}</a>{% if not forloop.last %} | {% endif %}{% endfor %}+ </p>+{% endif %}<p>You're getting this email because you're subscribed to this alert in PostHog.</p>{% endblock %}diff --git a/products/alerts/backend/apps.py b/products/alerts/backend/apps.pyindex 338c92d7536c..ae57f90995fd 100644--- a/products/alerts/backend/apps.py+++ b/products/alerts/backend/apps.py@@ -15,12 +15,13 @@ class AlertsConfig(AppConfig):from products.alerts.backend import activity_logging # noqa: F401, PLC0415# The platform cannot import this product, so it reaches this product's destinations, the schema- # an edit to an insight alert's copy is checked against, and the `$insight_alert_firing` events of- # an insight alert on the HogFunction path, here.+ # an edit to an insight alert's copy is checked against, and the `$insight_alert_firing` events and+ # native wording of an insight alert, here.from products.alerts.backend.facade.destinations import ( # noqa: PLC0415choose_delivery_path,list_delivery_destination_groups,)+ from products.alerts.backend.platform_alert_wording import describe_insight_transition # noqa: PLC0415from products.alerts.backend.platform_hooks import emit_insight_legacy_events # noqa: PLC0415from products.alerts.backend.platform_source_config import load_insight_source_config # noqa: PLC0415from products.alerts_platform.backend.facade.contracts import SourceKind # noqa: PLC0415@@ -28,10 +29,12 @@ class AlertsConfig(AppConfig):register_delivery_path_chooser,register_destination_resolver,register_legacy_event_emitter,+ register_source_describer,)from products.alerts_platform.backend.facade.source_configs import register_source_config # noqa: PLC0415register_destination_resolver(list_delivery_destination_groups)register_delivery_path_chooser(choose_delivery_path)register_legacy_event_emitter(SourceKind.INSIGHT, emit_insight_legacy_events)+ register_source_describer(SourceKind.INSIGHT, describe_insight_transition)register_source_config(SourceKind.INSIGHT, load_insight_source_config)diff --git a/products/alerts/backend/platform_alert_wording.py b/products/alerts/backend/platform_alert_wording.pynew file mode 100644index 000000000000..59c99add749f--- /dev/null+++ b/products/alerts/backend/platform_alert_wording.py@@ -0,0 +1,44 @@+"""The insight wording of a native message for an insight alert the platform delivers.++The platform alone can say only "Value: 150". The insight stack says which threshold the insight+crossed, names the insight, and links to it. The check records those beside its verdict, so the+describer reads them from the transition and does no I/O, as the platform requires.++Imported from `ready()`, so it stays light: no models, no query layer.+"""++from __future__ import annotations++from posthog.utils import absolute_uri++from products.alerts_platform.backend.facade.contracts import (+ AlertEventKind,+ AnnouncedTransition,+ MessageDetail,+ MessageLink,+ SourceDescription,+)+++def describe_insight_transition(*, project_id: int, transition: AnnouncedTransition) -> SourceDescription:+ detail = transition.source_detail+ breaches = (detail.get("breaches") or []) if transition.kind == AlertEventKind.FIRING else []+ insight_name = detail.get("insight_name")+ insight_short_id = detail.get("insight_short_id")+ return SourceDescription(+ # One detail for every breach, because a transport such as PagerDuty keys its details by label.+ details=(MessageDetail(label="Threshold breached", value="\n".join(breaches)),) if breaches else (),+ context=(f"Insight: {insight_name}",) if insight_name else (),+ data_link=MessageLink(label="View insight", url=insight_url(project_id, insight_short_id))+ if insight_short_id+ else None,+ )+++def insight_url(project_id: int, insight_short_id: str) -> str:+ return absolute_uri(f"/project/{project_id}/insights/{insight_short_id}")+++def insight_alert_url(project_id: int, insight_short_id: str, alert_id: str) -> str:+ """The alert's page on its insight, which the insight stack's messages link to."""+ return absolute_uri(f"/project/{project_id}/insights/{insight_short_id}/alerts?alert_id={alert_id}")diff --git a/products/alerts/backend/platform_source_cycle.py b/products/alerts/backend/platform_source_cycle.pyindex 68b0bd491f61..ffb00e791528 100644--- a/products/alerts/backend/platform_source_cycle.py+++ b/products/alerts/backend/platform_source_cycle.py@@ -47,6 +47,7 @@ from products.alerts.backend.judge.contract import (from products.alerts.backend.llm_detector_limits import is_llm_detector_configfrom products.alerts.backend.logic.alert_email import INSIGHT_ALERT_ERRORED_EVENT_IDfrom products.alerts.backend.models.alert import AlertConfiguration+from products.alerts.backend.platform_alert_wording import insight_alert_urlfrom products.alerts_platform.backend.facade.api import due_check_ids, due_checks, refresh_settings, slot_offrom products.alerts_platform.backend.facade.contracts import (SOURCE_CONDITION_KEY,@@ -379,6 +380,7 @@ def _delivery(check: PlatformAlertCheckInput, outcome: PlatformAlertOutcome) ->evaluation_key=outcome.evaluation_key,destination_alert_id=legacy_id,event_ids_by_kind=_EVENT_IDS_BY_KIND,+ source_alert_url=_alert_url(check, legacy_id),owned_by_platform=check.owned_by_platform,overflowed=outcome.overflowed,overflow_is_lower_bound=outcome.overflow_is_lower_bound,@@ -386,6 +388,16 @@ def _delivery(check: PlatformAlertCheckInput, outcome: PlatformAlertOutcome) ->)+def _alert_url(check: PlatformAlertCheckInput, legacy_id: str) -> str | None:+ """The alert's page on its insight, so a native message links where the insight stack's does."""+ insight_short_id = (+ AlertConfiguration.objects.filter(team_id=check.team_id, id=legacy_id)+ .values_list("insight__short_id", flat=True)+ .first()+ )+ return insight_alert_url(check.team_id, insight_short_id, legacy_id) if insight_short_id else None++def _legacy_alert(check: PlatformAlertCheckInput) -> AlertConfiguration | None:if check.legacy_configuration_id is None:return None@@ -454,7 +466,7 @@ def _decide(calculation_interval=alert.calculation_interval, organization=alert.team.organization)if entitlement_error:- return _broken(check, snapshot, now=now, message=entitlement_error)+ return _broken(check, snapshot, alert, now=now, message=entitlement_error)if skip_because_of_weekend(alert) or is_utc_datetime_blocked(alert, now):return _skipped(check, snapshot, now=now)if is_llm_detector_config(alert.detector_config) != uses_llm_detector:@@ -500,11 +512,12 @@ def _decide(CheckInput(threshold_breached=False, error_message=LLM_DETECTOR_UNAVAILABLE_MESSAGE),now=now,skip=SkipReason.QUERY_FAILED,+ context=_context(alert),)except (AlertExtractionError, LLMDetectorMisconfiguredError) as error:- return _broken(check, snapshot, now=now, message=str(error))+ return _broken(check, snapshot, alert, now=now, message=str(error))except Exception as error:- return _query_failed(check, snapshot, error, now=now)+ return _query_failed(check, snapshot, alert, error, now=now)duration_ms = int((time.monotonic() - started_at) * 1000)if result.skipped_reason is not None:@@ -547,7 +560,7 @@ def _following(check: PlatformAlertCheckInput, alert: AlertConfiguration) -> Pladef _broken(- check: PlatformAlertCheckInput, snapshot: AlertSnapshot, *, now: datetime, message: str+ check: PlatformAlertCheckInput, snapshot: AlertSnapshot, alert: AlertConfiguration, *, now: datetime, message: str) -> PlatformAlertOutcome:"""An alert production cannot evaluate as configured. It errors and is disabled, as production does."""return _recorded(@@ -560,11 +573,17 @@ def _broken(error_message=message,skip=SkipReason.BROKEN_CONFIG,disable=True,+ source_detail=_context(alert),)def _query_failed(- check: PlatformAlertCheckInput, snapshot: AlertSnapshot, error: Exception, *, now: datetime+ check: PlatformAlertCheckInput,+ snapshot: AlertSnapshot,+ alert: AlertConfiguration,+ error: Exception,+ *,+ now: datetime,) -> PlatformAlertOutcome:"""A query that did not finish. A refusal for load is a skip; anything else is a failed check."""if classify_query_error(error) == QueryErrorCategory.RATE_LIMITED:@@ -581,6 +600,7 @@ def _query_failed(),now=now,skip=SkipReason.QUERY_FAILED,+ context=_context(alert),)@@ -611,14 +631,16 @@ def _decide_grouped(value the query did not return is left as it is."""if tuple(check.grouping.keys) != (BREAKDOWN_GROUPING_KEY,):- return _broken(check, snapshot, now=now, message=f"An insight alert can only group by {BREAKDOWN_GROUPING_KEY}")+ return _broken(+ check, snapshot, alert, now=now, message=f"An insight alert can only group by {BREAKDOWN_GROUPING_KEY}"+ )started_at = time.monotonic()try:evaluated = check_alert_per_series(alert)except AlertExtractionError as error:- return _broken(check, snapshot, now=now, message=str(error))+ return _broken(check, snapshot, alert, now=now, message=str(error))except Exception as error:- return _query_failed(check, snapshot, error, now=now)+ return _query_failed(check, snapshot, alert, error, now=now)if not isinstance(evaluated, PerSeriesEvaluation):return _skipped(check, snapshot, now=now)duration_ms = int((time.monotonic() - started_at) * 1000)@@ -657,7 +679,7 @@ def _decide_grouped(verdict,group=replace(verdict.group,- source_detail=_detail(breaches.get(verdict.group.grouping_key, []), chart),+ source_detail=_detail(alert, breaches.get(verdict.group.grouping_key, []), chart),),)if verdict.outcome.notification == NotificationAction.FIRE@@ -678,7 +700,7 @@ def _firing_detail(check: PlatformAlertCheckInput, alert: AlertConfiguration, breaches: Sequence[str]) -> dict[str, Any]:"""What production's `$insight_alert_firing` carries beside the verdict, which only the check can know."""- return _detail(breaches, _chart(check, alert))+ return _detail(alert, breaches, _chart(check, alert))def _chart(check: PlatformAlertCheckInput, alert: AlertConfiguration) -> RenderedInsightChart | None:@@ -689,13 +711,21 @@ def _chart(check: PlatformAlertCheckInput, alert: AlertConfiguration) -> Renderereturn None+def _context(alert: AlertConfiguration) -> dict[str, Any]:+ """The insight a message names and links to, which every message about the alert carries."""+ return {"insight_name": alert.insight.name, "insight_short_id": alert.insight.short_id}++def _clipped(breach: str) -> str:return breach if len(breach) <= MAX_BREACH_CHARS else breach[: MAX_BREACH_CHARS - 1] + "…"-def _detail(breaches: Sequence[str], chart: RenderedInsightChart | None) -> dict[str, Any]:+def _detail(alert: AlertConfiguration, breaches: Sequence[str], chart: RenderedInsightChart | None) -> dict[str, Any]:# Bounded, because the outcome crosses into Temporal and a breach names user-written labels.- detail: dict[str, Any] = {"breaches": [_clipped(breach) for breach in breaches[:MAX_DETAIL_BREACHES]]}+ detail: dict[str, Any] = {+ "breaches": [_clipped(breach) for breach in breaches[:MAX_DETAIL_BREACHES]],+ **_context(alert),+ }if chart is not None:# The ids rather than a URL, because the URL opens the chart without a login and history keeps# this for its whole retention. A delivery mints the URL when it sends.@@ -714,13 +744,16 @@ def _verdict(query_duration_ms: int | None = None,skip: SkipReason | None = None,firing: tuple[AlertConfiguration, Sequence[str]] | None = None,+ context: dict[str, Any] | None = None,) -> PlatformAlertOutcome:outcome = evaluate_alert_check(snapshot, check_input, now, policy=INSIGHT_ALERT_POLICY)- source_detail = (- _firing_detail(check, *firing)- if firing is not None and outcome.notification == NotificationAction.FIRE- else None- )+ source_detail: dict[str, Any] | None+ if firing is not None and outcome.notification == NotificationAction.FIRE:+ source_detail = _firing_detail(check, *firing)+ elif outcome.notification != NotificationAction.NONE:+ source_detail = context+ else:+ source_detail = Nonereturn _recorded(check,snapshot,diff --git a/products/alerts/backend/test/test_platform_alert_wording.py b/products/alerts/backend/test/test_platform_alert_wording.pynew file mode 100644index 000000000000..1b7276d0ff52--- /dev/null+++ b/products/alerts/backend/test/test_platform_alert_wording.py@@ -0,0 +1,79 @@+from datetime import UTC, datetime+from typing import Any++from django.test import SimpleTestCase++from parameterized import parameterized++from posthog.utils import absolute_uri++from products.alerts.backend.platform_alert_wording import describe_insight_transition+from products.alerts_platform.backend.facade.contracts import (+ AlertEventKind,+ AnnouncedTransition,+ MessageDetail,+ MessageLink,+ SourceDescription,+)++DETAIL = {+ "breaches": ["Signups (50) is less than lower threshold (100)"],+ "insight_name": "Signups",+ "insight_short_id": "abc123",+}+LINK = MessageLink(label="View insight", url=absolute_uri("/project/7/insights/abc123"))+++class TestDescribeInsightTransition(SimpleTestCase):+ @parameterized.expand(+ [+ (+ "a_firing_states_its_breach_and_links_its_insight",+ AlertEventKind.FIRING,+ DETAIL,+ SourceDescription(+ details=(MessageDetail(label="Threshold breached", value=DETAIL["breaches"][0]),),+ context=("Insight: Signups",),+ data_link=LINK,+ ),+ ),+ (+ "every_breach_survives_a_transport_that_keys_details_by_label",+ AlertEventKind.FIRING,+ {**DETAIL, "breaches": ["Series A is above 10", "Series B is above 10"]},+ SourceDescription(+ details=(+ MessageDetail(label="Threshold breached", value="Series A is above 10\nSeries B is above 10"),+ ),+ context=("Insight: Signups",),+ data_link=LINK,+ ),+ ),+ # The platform states a failure in its own words, so only the insight's name and link are added.+ (+ "an_error_keeps_the_platform_failure_details",+ AlertEventKind.ERRORED,+ DETAIL,+ SourceDescription(context=("Insight: Signups",), data_link=LINK),+ ),+ # A row recorded before checks kept their detail falls back to the platform's wording.+ ("a_row_without_detail_says_nothing_extra", AlertEventKind.FIRING, {}, SourceDescription()),+ ]+ )+ def test_the_insight_words_a_native_message(+ self, _name: str, kind: AlertEventKind, detail: dict[str, Any], expected: SourceDescription+ ) -> None:+ transition = AnnouncedTransition(+ grouping_key="",+ kind=kind,+ episode_started_at=None,+ value=50.0,+ labels={},+ condition={},+ source_config={},+ error_message=None,+ occurred_at=datetime(2026, 10, 20, 9, 0, tzinfo=UTC),+ source_detail=detail,+ )++ assert describe_insight_transition(project_id=7, transition=transition) == expecteddiff --git a/products/alerts/backend/test/test_platform_source_cycle.py b/products/alerts/backend/test/test_platform_source_cycle.pyindex 843d8f836b1f..eb5ef3b3c057 100644--- a/products/alerts/backend/test/test_platform_source_cycle.py+++ b/products/alerts/backend/test/test_platform_source_cycle.py@@ -31,6 +31,7 @@ from products.alerts.backend.judge.contract import ()from products.alerts.backend.logic.alert_email import INSIGHT_ALERT_ERRORED_EVENT_IDfrom products.alerts.backend.models.alert import AlertCheck, AlertConfiguration+from products.alerts.backend.platform_alert_wording import insight_alert_urlfrom products.alerts.backend.platform_source_cycle import (CAPACITY_REJECTED,INFLIGHT_KEY,@@ -192,18 +193,21 @@ class TestPlatformInsightEvaluation(APIBaseTest):@parameterized.expand([- ("source_owned", "source", {"breaches": ["above 100"]}),- (- "platform_owned",- "platform",- {"breaches": ["above 100"], "insight_chart_asset_id": 7, "insight_chart_render_user_id": 3},- ),+ ("source_owned", "source", {}),+ ("platform_owned", "platform", {"insight_chart_asset_id": 7, "insight_chart_render_user_id": 3}),])def test_a_firing_records_what_production_sends_beside_it(- self, _name: str, owner: str, expected: dict[str, Any]+ self, _name: str, owner: str, chart: dict[str, Any]) -> None:- configuration = self._copy(self._alert(), owner=owner)+ alert = self._alert()+ configuration = self._copy(alert, owner=owner)+ expected = {+ "breaches": ["above 100"],+ "insight_name": alert.insight.name,+ "insight_short_id": alert.insight.short_id,+ **chart,+ }with patch(f"{_MODULE}.render_alert_insight_chart",@@ -364,6 +368,11 @@ class TestPlatformInsightEvaluation(APIBaseTest):)for delivery in self.deliveries] == (expected if (allowlisted or owned) and not was_firing else [])+ # A native message links to the alert on its insight, where the insight stack's messages link.+ assert all(+ delivery.source_alert_url == insight_alert_url(self.team.id, alert.insight.short_id, str(alert.id))+ for delivery in self.deliveries+ )@parameterized.expand([@@ -451,6 +460,8 @@ class TestPlatformInsightEvaluation(APIBaseTest):"errored",True,)+ # The error message names and links the insight, as a firing's does.+ assert set(outcome.failure.source_detail) == {"insight_name", "insight_short_id"}@parameterized.expand([("retried", False), ("last_attempt", True)])def test_an_ai_detector_without_a_verdict_is_retried_and_only_its_last_attempt_records_an_error(diff --git a/products/alerts_platform/backend/delivery/email.py b/products/alerts_platform/backend/delivery/email.pyindex 3b0014f553a9..d39f5c191467 100644--- a/products/alerts_platform/backend/delivery/email.py+++ b/products/alerts_platform/backend/delivery/email.py@@ -53,6 +53,8 @@ class EmailTransport:template_context={"headline": message.headline,"details": [{"label": detail.label, "value": detail.value} for detail in message.details],+ "context": list(message.context),+ "links": [{"label": link.label, "url": link.url} for link in message.links],},)except ImproperlyConfigured as error:diff --git a/products/alerts_platform/backend/facade/contracts.py b/products/alerts_platform/backend/facade/contracts.pyindex f122442275b9..235819d4db34 100644--- a/products/alerts_platform/backend/facade/contracts.py+++ b/products/alerts_platform/backend/facade/contracts.py@@ -585,6 +585,8 @@ class CheckFailure:notified: boolfiring_episode: FiringEpisode | None = Nonemuted_notification: str = ""+ # As on `GroupOutcome`: what the source's stack sends beside the failure, stored unread.+ source_detail: dict[str, Any] = field(default_factory=dict)@frozen@@ -658,6 +660,7 @@ class PlatformAlertOutcome:notified=notified,firing_episode=firing_episode,muted_notification=muted_notification,+ source_detail=source_detail or {},)if failedelse Nonediff --git a/products/alerts_platform/backend/logic/platform_lifecycle.py b/products/alerts_platform/backend/logic/platform_lifecycle.pyindex 2a5b600eb6e7..a8c2c653311d 100644--- a/products/alerts_platform/backend/logic/platform_lifecycle.py+++ b/products/alerts_platform/backend/logic/platform_lifecycle.py@@ -379,7 +379,7 @@ def _event_row(error_message=outcome.error_message,consecutive_failures=outcome.consecutive_failures,muted_notification=verdict.muted_notification,- source_detail=group.source_detail if group else None,+ source_detail=verdict.source_detail,now=now,)diff --git a/products/alerts_platform/backend/tests/test_delivery_email.py b/products/alerts_platform/backend/tests/test_delivery_email.pyindex 2b9a024a9f51..5b55a9f7a346 100644--- a/products/alerts_platform/backend/tests/test_delivery_email.py+++ b/products/alerts_platform/backend/tests/test_delivery_email.py@@ -65,15 +65,24 @@ class TestEmailTransport(SimpleTestCase):with pytest.raises(DeliveryError, match="not configured"):EmailTransport().deliver(team_id=2, target=TARGET, message=alert_message())- def test_the_template_renders_the_headline_and_every_detail(self) -> None:+ def test_the_template_renders_the_headline_details_context_and_links(self) -> None:html = render_to_string(f"email/{TEMPLATE_NAME}.html",{"headline": "API errors is firing","details": [{"label": "Value", "value": "312"}, {"label": "Threshold", "value": "> 300"}],+ "context": ["Insight: Signups"],+ "links": [{"label": "View insight", "url": "https://app.example.com/insights/abc"}],},)assert "API errors is firing" in htmlassert "Value:</strong> 312" in htmlassert "Threshold:</strong> > 300" in html+ assert "Insight: Signups" in html+ assert '<a href="https://app.example.com/insights/abc">View insight</a>' in html++ def test_an_email_carries_the_message_context_and_links(self) -> None:+ kwargs = self._deliver().call_args.kwargs++ assert [link["label"] for link in kwargs["template_context"]["links"]] == ["View alert"]diff --git a/products/alerts_platform/backend/tests/test_delivery_evaluation.py b/products/alerts_platform/backend/tests/test_delivery_evaluation.pyindex 7cc0c79e478c..ae419e52df4f 100644--- a/products/alerts_platform/backend/tests/test_delivery_evaluation.py+++ b/products/alerts_platform/backend/tests/test_delivery_evaluation.py@@ -10,7 +10,7 @@ from unittest.mock import patchfrom parameterized import parameterized-from products.alerts_platform.backend.delivery import delivery_paths, legacy_webhook+from products.alerts_platform.backend.delivery import delivery_paths, describers, legacy_webhookfrom products.alerts_platform.backend.delivery.destinations import list_alert_destination_groupsfrom products.alerts_platform.backend.delivery.evaluation import LIVE_DELIVERY_FLAG, deliver_evaluationfrom products.alerts_platform.backend.delivery.legacy_webhook import LEGACY_WEBHOOK_BODY_FLAG@@ -537,6 +537,8 @@ class TestDeliverEvaluation(APIBaseTest):assert delivery_paths._chooser is not None# Without it an insight alert on the HogFunction path sends nothing at all.assert delivery_paths.emitter_for(SourceKind.INSIGHT) is not None+ # Without it a native insight message carries only the platform's "Value" line.+ assert SourceKind.INSIGHT in describers._describersassert (list_alert_destination_groups(team_id=self.team.id, alert_id="unknown", allowed_event_ids=[FIRING_EVENT])== []