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(signals): add guidance to the product analytics source (#129233)

Andrew Maguiref0d2dd2444ad
diff --git a/products/signals/ARCHITECTURE.md b/products/signals/ARCHITECTURE.md
index 63638039d30b..affb60de9e47 100644
--- a/products/signals/ARCHITECTURE.md
+++ b/products/signals/ARCHITECTURE.md
@@ -680,6 +680,7 @@ Per-team configuration for which signal sources are enabled.
The read does not check `enabled`: the emitter still gates on `is_source_enabled`.
With `all_firing_alerts`, insight alert evaluation (`posthog/temporal/alerts/alert_firing_signal.py`) emits `analytics` / `alert_firing` when an alert that the investigation agent does not investigate starts a firing episode. It emits once per episode (source id and idempotency key `<alert id>:<first check id>`), and a failure never changes the check. The evaluation thread runs the gates after the check is committed. The activity awaits the emission on its event loop once that thread returns, because `emit_signal` needs the default executor that the thread runs on. A per-team token bucket caps it, and an unavailable bucket skips the signal. Each skip after a read logs `alert_firing.signal_skipped` with a reason. Alerts the agent investigates keep the verdict gate in both scopes.
`alert_firing` has no config row of its own: `is_source_enabled` checks the `anomaly_investigation` row for it, so the one product analytics toggle turns both off.
+ Guidance written on that row filters both `anomaly_investigation` and `alert_firing`, through the direct steering gate.
- The serializer exposes a computed `status` field:
- data-import-backed sources (`github`, `linear`, `zendesk`) derive status from `ExternalDataSchema`
- The `signals_scout` source variant pairs with `source_type=cross_source_issue` and is the emission channel used by the headless Signals agent's `emit_signal_*` tools. It is the only `(source_product, source_type)` pair the agent emits today.
diff --git a/products/signals/backend/contracts.py b/products/signals/backend/contracts.py
index fb7ffdea0971..5e7f97411c3f 100644
--- a/products/signals/backend/contracts.py
+++ b/products/signals/backend/contracts.py
@@ -71,6 +71,8 @@ DIRECT_STEERABLE_SOURCES: frozenset[tuple[str, str]] = frozenset(
(SignalSourceProduct.ERROR_TRACKING, SignalSourceType.ISSUE_REOPENED),
(SignalSourceProduct.ERROR_TRACKING, SignalSourceType.ISSUE_SPIKING),
(SignalSourceProduct.HEALTH_CHECKS, SignalSourceType.HEALTH_ISSUE),
+ (SignalSourceProduct.ANALYTICS, SignalSourceType.ANOMALY_INVESTIGATION),
+ (SignalSourceProduct.ANALYTICS, SignalSourceType.ALERT_FIRING),
}
)
diff --git a/products/signals/backend/emission/steering.py b/products/signals/backend/emission/steering.py
index 278cadd302b6..8925fdfafc38 100644
--- a/products/signals/backend/emission/steering.py
+++ b/products/signals/backend/emission/steering.py
@@ -107,7 +107,11 @@ def apply_steering(prompt: str, steering: SourceSteering) -> str:
async def afetch_source_config(team_id: int, source_product: str, source_type: str) -> dict[str, Any]:
"""The team's ``SignalSourceConfig.config`` blob for one emission source, or ``{}``."""
config = (
- await SignalSourceConfig.objects.filter(team_id=team_id, source_product=source_product, source_type=source_type)
+ await SignalSourceConfig.objects.filter(
+ team_id=team_id,
+ source_product=source_product,
+ source_type=SignalSourceConfig.config_source_type(source_product, source_type),
+ )
.values_list("config", flat=True)
.afirst()
)
diff --git a/products/signals/backend/emission/tests/test_direct_gate.py b/products/signals/backend/emission/tests/test_direct_gate.py
index 0eaeea4d54df..7d4bf3216e11 100644
--- a/products/signals/backend/emission/tests/test_direct_gate.py
+++ b/products/signals/backend/emission/tests/test_direct_gate.py
@@ -162,7 +162,17 @@ class TestSteeringFiltersSignal:
class TestEmitSignalWiring:
@pytest.mark.asyncio
- async def test_emit_signal_consults_the_gate_and_drops_a_filtered_signal_before_queueing(self):
+ @pytest.mark.parametrize(
+ "source_product,source_type",
+ [
+ ("error_tracking", "issue_created"),
+ ("analytics", "anomaly_investigation"),
+ ("analytics", "alert_firing"),
+ ],
+ )
+ async def test_emit_signal_consults_the_gate_and_drops_a_filtered_signal_before_queueing(
+ self, source_product: str, source_type: str
+ ):
# The gate reaches production only through the membership check in `emit_signal`, whose
# `(source_product, source_type)` tuple has to match the enum values the set is built from.
team = _make_team()
@@ -174,13 +184,14 @@ class TestEmitSignalWiring:
patch(f"{FACADE_MODULE_PATH}.async_connect", connect),
patch(f"{FACADE_MODULE_PATH}.complete_signal_pipeline"),
patch(f"{FACADE_MODULE_PATH}.finalized_signal_ids", return_value=set()),
+ patch(f"{FACADE_MODULE_PATH}.validate_signal_input", return_value=None),
patch(f"{GATE_MODULE_PATH}.steering_filters_signal", AsyncMock(return_value=True)) as gate,
):
source_config.is_source_enabled.return_value = True
await emit_signal(
team=team,
- source_product="error_tracking",
- source_type="issue_created",
+ source_product=source_product,
+ source_type=source_type,
source_id="record-1",
description="Something happened",
extra={"fingerprint": "abc123"},
diff --git a/products/signals/backend/models.py b/products/signals/backend/models.py
index 17651583f530..79ea8a9bba1e 100644
--- a/products/signals/backend/models.py
+++ b/products/signals/backend/models.py
@@ -134,6 +134,20 @@ class SignalSourceConfig(UUIDModel):
updated_at = models.DateTimeField(auto_now=True)
created_by = models.ForeignKey("posthog.User", on_delete=models.SET_NULL, null=True, blank=True, related_name="+")
+ @classmethod
+ def config_source_type(cls, source_product: str, source_type: str) -> str:
+ """The `source_type` of the row that configures a signal, which another type can own."""
+ # Session problem signals are emitted as part of session analysis,
+ # so they're gated by the pre-existing session_analysis_cluster config
+ if source_product == cls.SourceProduct.SESSION_REPLAY and source_type == "session_problem":
+ return cls.SourceType.SESSION_ANALYSIS_CLUSTER
+
+ # Firing alerts are a scope of the product analytics source, so they share its row and toggle.
+ if source_product == cls.SourceProduct.ANALYTICS and source_type == SignalSourceType.ALERT_FIRING:
+ return cls.SourceType.ANOMALY_INVESTIGATION
+
+ return source_type
+
@classmethod
def is_source_enabled(cls, team_id: int, source_product: str, source_type: str) -> bool:
"""Check whether a given signal source is enabled for a team.
@@ -165,19 +179,10 @@ class SignalSourceConfig(UUIDModel):
enabled=False,
).exists()
- # Session problem signals are emitted as part of session analysis,
- # so they're gated by the pre-existing session_analysis_cluster config
- if source_product == cls.SourceProduct.SESSION_REPLAY and source_type == "session_problem":
- source_type = cls.SourceType.SESSION_ANALYSIS_CLUSTER
-
- # Firing alerts are a scope of the product analytics source, so they share its row and toggle.
- if source_product == cls.SourceProduct.ANALYTICS and source_type == SignalSourceType.ALERT_FIRING:
- source_type = cls.SourceType.ANOMALY_INVESTIGATION
-
return cls.objects.filter(
team_id=team_id,
source_product=source_product,
- source_type=source_type,
+ source_type=cls.config_source_type(source_product, source_type),
enabled=True,
).exists()
diff --git a/products/signals/backend/test/test_signal_source_config_api.py b/products/signals/backend/test/test_signal_source_config_api.py
index 0f5107c49841..99e1582aee77 100644
--- a/products/signals/backend/test/test_signal_source_config_api.py
+++ b/products/signals/backend/test/test_signal_source_config_api.py
@@ -9,6 +9,7 @@ from unittest.mock import patch
from django.db import connection, connections
from django.test import SimpleTestCase
+from asgiref.sync import async_to_sync
from parameterized import parameterized
from rest_framework import status
from rest_framework.test import APIClient
@@ -18,6 +19,7 @@ from posthog.models.personal_api_key import PersonalAPIKey
from posthog.models.team.team import Team
from posthog.models.utils import generate_random_token_personal, hash_key_value
+from products.signals.backend.emission.steering import afetch_source_config
from products.signals.backend.facade.source_configs import get_analytics_alert_scope
from products.signals.backend.models import SignalSourceConfig
from products.signals.backend.serializers import SignalSourceConfigSerializer
@@ -754,9 +756,12 @@ class TestIsSourceEnabledGating(APIBaseTest):
source_product=SignalSourceConfig.SourceProduct.ANALYTICS,
source_type=SignalSourceConfig.SourceType.ANOMALY_INVESTIGATION,
enabled=existing_enabled,
+ config={"steering": "Skip the staging alerts."},
)
assert SignalSourceConfig.is_source_enabled(self.team.id, "analytics", "alert_firing") is expected
+ steering = async_to_sync(afetch_source_config)(self.team.id, "analytics", "alert_firing").get("steering")
+ assert steering == (None if existing_enabled is None else "Skip the staging alerts.")
def test_pganalyze_issue_requires_own_config(self):
SignalSourceConfig.objects.create(
diff --git a/products/signals/frontend/inbox/components/config/AgentsRoster.tsx b/products/signals/frontend/inbox/components/config/AgentsRoster.tsx
index 033ff6ab009f..270ee7fe231c 100644
--- a/products/signals/frontend/inbox/components/config/AgentsRoster.tsx
+++ b/products/signals/frontend/inbox/components/config/AgentsRoster.tsx
@@ -760,6 +760,7 @@ export function AgentsRoster(): JSX.Element {
loading: isAnomalyInvestigationToggling,
requiresSetup: false,
syncStatus: anomalyInvestigationConfig?.status,
+ steeringConfigs: anomalyInvestigationConfig ? [anomalyInvestigationConfig] : [],
}
case 'health_checks':
return {
diff --git a/products/signals/frontend/inbox/components/config/agentRosterMeta.ts b/products/signals/frontend/inbox/components/config/agentRosterMeta.ts
index 8710994bc1fb..81cd481347fa 100644
--- a/products/signals/frontend/inbox/components/config/agentRosterMeta.ts
+++ b/products/signals/frontend/inbox/components/config/agentRosterMeta.ts
@@ -127,6 +127,7 @@ export const AGENT_ROSTER_GROUPS: AgentRosterGroup[] = [
detail: 'Fires when an anomaly alert goes off, and only for the alerts where you turned the investigation agent on.',
docsUrl: 'https://posthog.com/docs/product-analytics',
docsLabel: 'Product analytics',
+ steerable: true,
alpha: true,
},
{