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.

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.html
index 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.py
index 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: PLC0415
choose_delivery_path,
list_delivery_destination_groups,
)
+ from products.alerts.backend.platform_alert_wording import describe_insight_transition # noqa: PLC0415
from products.alerts.backend.platform_hooks import emit_insight_legacy_events # noqa: PLC0415
from products.alerts.backend.platform_source_config import load_insight_source_config # noqa: PLC0415
from 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: PLC0415
register_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.py
new file mode 100644
index 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.py
index 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_config
from products.alerts.backend.logic.alert_email import INSIGHT_ALERT_ERRORED_EVENT_ID
from products.alerts.backend.models.alert import AlertConfiguration
+from products.alerts.backend.platform_alert_wording import insight_alert_url
from products.alerts_platform.backend.facade.api import due_check_ids, due_checks, refresh_settings, slot_of
from 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) -> Pla
def _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) -> Rendere
return 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 = None
return _recorded(
check,
snapshot,
diff --git a/products/alerts/backend/test/test_platform_alert_wording.py b/products/alerts/backend/test/test_platform_alert_wording.py
new file mode 100644
index 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) == expected
diff --git a/products/alerts/backend/test/test_platform_source_cycle.py b/products/alerts/backend/test/test_platform_source_cycle.py
index 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_ID
from products.alerts.backend.models.alert import AlertCheck, AlertConfiguration
+from products.alerts.backend.platform_alert_wording import insight_alert_url
from 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.py
index 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.py
index 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: bool
firing_episode: FiringEpisode | None = None
muted_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 failed
else None
diff --git a/products/alerts_platform/backend/logic/platform_lifecycle.py b/products/alerts_platform/backend/logic/platform_lifecycle.py
index 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.py
index 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 html
assert "Value:</strong> 312" in html
assert "Threshold:</strong> &gt; 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.py
index 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 patch
from 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_webhook
from products.alerts_platform.backend.delivery.destinations import list_alert_destination_groups
from products.alerts_platform.backend.delivery.evaluation import LIVE_DELIVERY_FLAG, deliver_evaluation
from 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._describers
assert (
list_alert_destination_groups(team_id=self.team.id, alert_id="unknown", allowed_event_ids=[FIRING_EVENT])
== []