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.

chore(dev): match production person-on-events mode in local dev (#120227)

Thomas Obermüller9053daf3f111
diff --git a/docs/internal/dev-env-vars.md b/docs/internal/dev-env-vars.md
index e502249c60cc..13133d3a7163 100644
--- a/docs/internal/dev-env-vars.md
+++ b/docs/internal/dev-env-vars.md
@@ -45,4 +45,16 @@ Code that branches on the literal region (`get_instance_region()`, `region == "U
`COMPACT_IN_REGION` controls which Cloud region registers the daily AI checkpoint compaction schedule. It defaults to `US`; set it explicitly only when moving the rollout to another region.
+## Person-on-events mode in local dev
+
+Nearly every production project reads person properties off events, because the `persons-on-events-v2-reads-enabled` flag is at 100% for organizations created after 2024-06-14.
+That flag is only consulted when `is_cloud()` is true, so a local team falls back to the `PERSON_ON_EVENTS_V2_ENABLED` instance setting instead.
+The setting defaults on under `DEBUG`, which keeps a local stack on the same query path as production.
+Before that default, every local team resolved to the legacy `person_id_override_properties_joined` mode, and UI gated on `person_on_events_querying_enabled`, such as the persons-modal properties timeline, never rendered locally.
+
+To work on the legacy mode, set `PERSON_ON_EVENTS_V2_ENABLED=0` in `.env.local`, or set `personsOnEventsMode` in the team's `modifiers`, which takes precedence over the setting.
+
+The frontend reads `person_on_events_querying_enabled` from the server-rendered `window.POSTHOG_APP_CONTEXT`, which `teamLogic` seeds once on mount.
+A change to the setting or to a team's modifiers therefore needs a full page reload. Navigating within the app keeps the stale value.
+
See also [sandboxes-setup-guide.md](sandboxes-setup-guide.md) for the PostHog Desktop sandbox providers.
diff --git a/posthog/api/test/test_playwright_setup.py b/posthog/api/test/test_playwright_setup.py
index f00cd3d998ff..9a384eab9c7b 100644
--- a/posthog/api/test/test_playwright_setup.py
+++ b/posthog/api/test/test_playwright_setup.py
@@ -1,10 +1,16 @@
+import json
+
from posthog.test.base import APIBaseTest
from django.test import override_settings
from rest_framework import status
+from posthog.schema import PersonsOnEventsMode
+
+from posthog.clickhouse.client import sync_execute
from posthog.models import Organization, PersonalAPIKey, Team, User
+from posthog.models.instance_setting import override_instance_config
class TestPlaywrightSetup(APIBaseTest):
@@ -65,6 +71,53 @@ class TestPlaywrightSetup(APIBaseTest):
self.assertIn("*", api_key.scopes) # Should have full access
self.assertTrue(result["personal_api_key"].startswith("phx_"))
+ @override_settings(TEST=True)
+ def test_organization_with_team_pins_the_production_person_on_events_mode(self):
+ # The instance setting is off on purpose, so the assertion proves the team's own modifiers
+ # rather than the ambient setting. Playwright CI runs with it unset and DEBUG off.
+ with override_instance_config("PERSON_ON_EVENTS_V2_ENABLED", False):
+ response = self.client.post(
+ "/api/setup_test/organization_with_team/", {"no_demo_data": True}, format="json"
+ )
+ self.assertEqual(response.status_code, status.HTTP_200_OK)
+
+ team = Team.objects.get(id=response.json()["result"]["team_id"])
+ self.assertEqual(team.person_on_events_mode, PersonsOnEventsMode.PERSON_ID_OVERRIDE_PROPERTIES_ON_EVENTS)
+ self.assertTrue(team.person_on_events_querying_enabled)
+
+ @override_settings(TEST=True)
+ def test_seeded_events_carry_person_properties_as_of_each_event(self):
+ # A person-on-events mode reads person properties off the event, not the person table.
+ payload = {
+ "no_demo_data": True,
+ "persons": [{"distinct_ids": ["seeded-person"], "properties": {"plan": "free"}}],
+ "events": [
+ {
+ "event": "$pageview",
+ "distinct_id": "seeded-person",
+ "timestamp": "2024-11-03T10:00:00Z",
+ },
+ {
+ "event": "$pageview",
+ "distinct_id": "seeded-person",
+ "timestamp": "2024-11-03T12:00:00Z",
+ "properties": {"$set": {"plan": "paid"}},
+ },
+ ],
+ }
+ response = self.client.post("/api/setup_test/organization_with_team/", payload, format="json")
+ self.assertEqual(response.status_code, status.HTTP_200_OK)
+
+ team_id = int(response.json()["result"]["team_id"])
+ rows = sync_execute(
+ "SELECT person_properties FROM events WHERE team_id = %(team_id)s ORDER BY timestamp",
+ {"team_id": team_id},
+ )
+ self.assertEqual(
+ [json.loads(row[0]) for row in rows],
+ [{"plan": "free"}, {"plan": "paid"}],
+ )
+
@override_settings(DEBUG=True)
def test_endpoint_allowed_in_debug_mode(self):
"""Test that the endpoint works in DEBUG mode"""
diff --git a/posthog/settings/dynamic_settings.py b/posthog/settings/dynamic_settings.py
index 4cb7be6b9809..177f7fe51fca 100644
--- a/posthog/settings/dynamic_settings.py
+++ b/posthog/settings/dynamic_settings.py
@@ -1,4 +1,4 @@
-from posthog.settings.base_variables import TEST
+from posthog.settings.base_variables import DEBUG, TEST
from posthog.settings.utils import get_from_env, str_to_bool
CONSTANCE_DATABASE_PREFIX = "constance:posthog:"
@@ -88,9 +88,15 @@ CONSTANCE_CONFIG = {
# test run that leaves it unset, such as `hogli test products/<name>`, reads the
# legacy joined mode instead and fails against snapshots that CI recorded under
# v2. The test-mode default carries the same value so a local run matches CI.
+ # DEBUG carries the same value, so a local team resolves the mode a production
+ # project resolves, and code that branches on the mode stays reachable locally.
+ # The persons-modal properties timeline is the visible case: the frontend gates
+ # it on team.person_on_events_querying_enabled, which the legacy joined mode
+ # makes false. DEBUG cannot be on in a deployed cloud environment, because
+ # assert_debug_not_in_production refuses to boot, so this reaches local dev only.
# Production and self-hosted keep the off default. A test that needs the legacy
# mode pins it with override_settings or override_instance_config.
- get_from_env("PERSON_ON_EVENTS_V2_ENABLED", TEST, type_cast=str_to_bool),
+ get_from_env("PERSON_ON_EVENTS_V2_ENABLED", TEST or DEBUG, type_cast=str_to_bool),
"Whether to use query path using person_id and person_properties on events or the old query",
bool,
),
diff --git a/posthog/test/playwright_setup_functions.py b/posthog/test/playwright_setup_functions.py
index fb3390a44ada..a82a6f9bef70 100644
--- a/posthog/test/playwright_setup_functions.py
+++ b/posthog/test/playwright_setup_functions.py
@@ -11,6 +11,8 @@ from django.utils import timezone
from pydantic import BaseModel
+from posthog.schema import PersonsOnEventsMode
+
from posthog.clickhouse.query_tagging import Feature, Product, tags_context
from posthog.constants import AvailableFeature
from posthog.management.commands.generate_demo_data import Command as GenerateDemoDataCommand
@@ -225,6 +227,15 @@ def create_organization_with_team(
update_fields.append("is_staff")
user.save(update_fields=update_fields)
+ # Pin the mode almost every production project runs on. Without this the mode follows the
+ # environment: Playwright CI leaves the PERSON_ON_EVENTS_* variables unset and runs with
+ # DEBUG off, while the local e2e stack sets PERSON_ON_EVENTS_OVERRIDE.
+ team.modifiers = {
+ **(team.modifiers or {}),
+ "personsOnEventsMode": PersonsOnEventsMode.PERSON_ID_OVERRIDE_PROPERTIES_ON_EVENTS.value,
+ }
+ team_update_fields = ["modifiers"]
+
# Skip all onboarding tasks if requested (prevents Quick Start popover in tests)
if data.skip_onboarding:
team.onboarding_tasks = {
@@ -246,7 +257,9 @@ def create_organization_with_team(
"create_experiment": "completed",
"launch_experiment": "completed",
}
- team.save()
+ team_update_fields.append("onboarding_tasks")
+
+ team.save(update_fields=team_update_fields)
created_variables = _create_variables(data, team)
created_insights = _create_insights(data, team, user, created_variables)
@@ -511,8 +524,25 @@ def _create_events_and_persons(
baseline_count = _count_events_in_clickhouse(team.pk)
- for event_spec in events:
- ts = datetime.fromisoformat(event_spec.timestamp.replace("Z", "+00:00"))
+ dated_events = [
+ (datetime.fromisoformat(event_spec.timestamp.replace("Z", "+00:00")), event_spec) for event_spec in events
+ ]
+
+ # A person-on-events mode resolves `events.person.properties` from the event's own
+ # person_properties column, not from the person table. Apply each $set in timestamp order,
+ # the way ingestion does, so an event carries the properties set by the time it happened.
+ properties_so_far: dict[str, dict[str, Any]] = {
+ distinct_id: dict(person_spec.properties or {})
+ for person_spec in (persons or [])
+ for distinct_id in person_spec.distinct_ids
+ }
+ person_properties_per_event: list[dict[str, Any]] = [{} for _ in dated_events]
+ for index, (_, event_spec) in sorted(enumerate(dated_events), key=lambda item: item[1][0]):
+ person_properties = properties_so_far.setdefault(event_spec.distinct_id, {})
+ person_properties.update((event_spec.properties or {}).get("$set") or {})
+ person_properties_per_event[index] = dict(person_properties)
+
+ for (ts, event_spec), person_properties in zip(dated_events, person_properties_per_event):
create_event(
event_uuid=UUIDT(unix_time_ms=int(ts.timestamp() * 1000)),
event=event_spec.event,
@@ -521,6 +551,7 @@ def _create_events_and_persons(
timestamp=ts,
properties=event_spec.properties or {},
person_id=uuid_module.UUID(person_uuids[event_spec.distinct_id]),
+ person_properties=person_properties,
)
_wait_for_events_in_clickhouse(team.pk, baseline_count + len(events))