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(retention): track saved event retention settings (#128960)

Paul D'Ambra86ea89e9bd33
diff --git a/products/product_analytics/backend/events_retention.py b/products/product_analytics/backend/events_retention.py
index ae7993113860..fc5400130adb 100644
--- a/products/product_analytics/backend/events_retention.py
+++ b/products/product_analytics/backend/events_retention.py
@@ -1,6 +1,9 @@
+from functools import partial
+
from django.core.exceptions import ValidationError
from django.db import transaction
+from posthog.event_usage import EventSource, report_user_action, sanitize_header_value
from posthog.models.activity_logging.activity_log import Change, Detail, log_activity
from posthog.models.events_retention_config import (
OrganizationEventsRetentionConfig,
@@ -16,6 +19,61 @@ from posthog.models.user import User
from products.product_analytics.backend.facade.contracts import OrganizationEventsRetention
+def _report_retention_set(
+ organization: Organization,
+ team: Team | None,
+ user: User,
+ before: int | None,
+ months: int | None,
+ analytics_properties: dict[str, object] | None,
+ was_impersonated: bool,
+) -> None:
+ properties: dict[str, object] = {"source": "unknown"}
+ for key in (
+ "source",
+ "$current_url",
+ "$host",
+ "$pathname",
+ "$session_id",
+ "access_method",
+ "user_agent",
+ "mcp_user_agent",
+ "mcp_client_name",
+ "mcp_client_version",
+ "mcp_protocol_version",
+ "mcp_oauth_client_name",
+ "$mcp_session_id",
+ "$mcp_conversation_id",
+ "$ai_trace_id",
+ ):
+ value = (analytics_properties or {}).get(key)
+ if isinstance(value, str) and (sanitized := sanitize_header_value(value)):
+ properties[key] = sanitized
+ if properties["source"] not in {source.value for source in EventSource}:
+ properties["source"] = "unknown"
+ properties.update(
+ {
+ "scope": "project" if team else "organization",
+ "organization_id": str(organization.id),
+ "retention_months": months,
+ "previous_retention_months": before,
+ "was_impersonated": was_impersonated,
+ }
+ )
+ if team:
+ properties["project_id"] = team.id
+ transaction.on_commit(
+ partial(
+ report_user_action,
+ user,
+ "events retention set",
+ properties,
+ organization=organization,
+ team=team,
+ )
+ )
+
+
def organization_events_retention(organization: Organization) -> OrganizationEventsRetention:
config = OrganizationEventsRetentionConfig.objects.filter(organization_id=organization.id).first()
plan_months = organization_events_retention_months(organization)
@@ -44,7 +102,12 @@ def _check_allowed(retention: OrganizationEventsRetention, months: int | None) -
def set_organization_events_retention(
- organization: Organization, months: int | None, *, user: User, was_impersonated: bool
+ organization: Organization,
+ months: int | None,
+ *,
+ user: User,
+ was_impersonated: bool,
+ analytics_properties: dict[str, object] | None = None,
) -> None:
with transaction.atomic():
# Lock before reading, because save() writes the staff range too and must not write back a stale one.
@@ -61,6 +124,7 @@ def set_organization_events_retention(
config.delete()
else:
config.save()
+ _report_retention_set(organization, None, user, before, months, analytics_properties, was_impersonated)
log_activity(
organization_id=organization.id,
@@ -79,7 +143,14 @@ def set_organization_events_retention(
)
-def set_project_events_retention(team: Team, months: int | None, *, user: User, was_impersonated: bool) -> None:
+def set_project_events_retention(
+ team: Team,
+ months: int | None,
+ *,
+ user: User,
+ was_impersonated: bool,
+ analytics_properties: dict[str, object] | None = None,
+) -> None:
with transaction.atomic():
config = TeamEventsRetentionConfig.objects.filter(team_id=team.id).first()
before = config.events_retention_months if config else None
@@ -93,6 +164,7 @@ def set_project_events_retention(team: Team, months: int | None, *, user: User,
config.events_retention_months = months
config.full_clean()
config.save()
+ _report_retention_set(team.organization, team, user, before, months, analytics_properties, was_impersonated)
log_activity(
organization_id=team.organization_id,
diff --git a/products/product_analytics/backend/facade/events_retention.py b/products/product_analytics/backend/facade/events_retention.py
index ebf42e79047f..8ccf92cff8d3 100644
--- a/products/product_analytics/backend/facade/events_retention.py
+++ b/products/product_analytics/backend/facade/events_retention.py
@@ -23,14 +23,28 @@ def project_events_retention_months(team: Team) -> int | None:
def set_organization_events_retention(
- organization: Organization, months: int | None, *, user: User, was_impersonated: bool
+ organization: Organization,
+ months: int | None,
+ *,
+ user: User,
+ was_impersonated: bool,
+ analytics_properties: dict[str, object] | None = None,
) -> None:
"""Set or clear the organization's window. Raises a Django ValidationError for a window outside the range."""
events_retention.set_organization_events_retention(
- organization, months, user=user, was_impersonated=was_impersonated
+ organization, months, user=user, was_impersonated=was_impersonated, analytics_properties=analytics_properties
)
-def set_project_events_retention(team: Team, months: int | None, *, user: User, was_impersonated: bool) -> None:
+def set_project_events_retention(
+ team: Team,
+ months: int | None,
+ *,
+ user: User,
+ was_impersonated: bool,
+ analytics_properties: dict[str, object] | None = None,
+) -> None:
"""Set or clear the project's window. Raises a Django ValidationError for a window outside the range."""
- events_retention.set_project_events_retention(team, months, user=user, was_impersonated=was_impersonated)
+ events_retention.set_project_events_retention(
+ team, months, user=user, was_impersonated=was_impersonated, analytics_properties=analytics_properties
+ )
diff --git a/products/product_analytics/backend/presentation/events_retention.py b/products/product_analytics/backend/presentation/events_retention.py
index f61338900698..c15bb04cb5ff 100644
--- a/products/product_analytics/backend/presentation/events_retention.py
+++ b/products/product_analytics/backend/presentation/events_retention.py
@@ -9,6 +9,7 @@ from rest_framework.response import Response
from posthog.api.mixins import ValidatedRequest, validated_request
from posthog.api.routing import TeamAndOrgViewSetMixin
+from posthog.event_usage import get_request_analytics_properties
from posthog.helpers.impersonation import is_impersonated
from posthog.models.team.event_retention import events_retention_floor_date, events_retention_months_for_team
from posthog.models.user import User
@@ -24,6 +25,19 @@ from products.product_analytics.backend.facade.events_retention import (
EVENTS_RETENTION_DOCS_URL = "https://posthog.com/docs/data/events-retention"
+def _retention_analytics_properties(request: Request) -> dict[str, object]:
+ try:
+ properties: dict[str, object] = {**get_request_analytics_properties(request)}
+ except ValueError:
+ properties = {}
+ return {
+ **properties,
+ "$mcp_session_id": request.headers.get("X-Posthog-Mcp-Session-Id"),
+ "$mcp_conversation_id": request.headers.get("X-Posthog-Mcp-Conversation-Id"),
+ "$ai_trace_id": request.headers.get("X-PostHog-Trace-Id"),
+ }
+
+
@extend_schema_serializer(many=False)
class OrganizationEventsRetentionSerializer(serializers.Serializer):
organization_retention_months = serializers.IntegerField(
@@ -137,6 +151,7 @@ class EventsRetentionViewSet(TeamAndOrgViewSetMixin, viewsets.ViewSet):
request.validated_data["retention_months"],
user=cast(User, request.user),
was_impersonated=is_impersonated(request),
+ analytics_properties=_retention_analytics_properties(request),
)
except DjangoValidationError as error:
raise exceptions.ValidationError(error.messages) from error
@@ -197,6 +212,7 @@ class OrganizationEventsRetentionViewSet(TeamAndOrgViewSetMixin, viewsets.ViewSe
request.validated_data["retention_months"],
user=cast(User, request.user),
was_impersonated=is_impersonated(request),
+ analytics_properties=_retention_analytics_properties(request),
)
except DjangoValidationError as error:
raise exceptions.ValidationError(error.messages) from error
diff --git a/products/product_analytics/backend/tests/api/test_events_retention.py b/products/product_analytics/backend/tests/api/test_events_retention.py
index 7774ec6f17b8..4e84a7127777 100644
--- a/products/product_analytics/backend/tests/api/test_events_retention.py
+++ b/products/product_analytics/backend/tests/api/test_events_retention.py
@@ -1,6 +1,8 @@
import time_machine
from posthog.test.base import APIBaseTest
+from unittest.mock import patch
+from django.db import transaction
from django.test import override_settings
from parameterized import parameterized
@@ -12,6 +14,10 @@ from posthog.models.events_retention_config import OrganizationEventsRetentionCo
from posthog.models.organization import OrganizationMembership
from products.access_control.backend.facade.testing import create_access_control
+from products.product_analytics.backend.facade.events_retention import (
+ set_organization_events_retention,
+ set_project_events_retention,
+)
@override_settings(EVENTS_DATA_RETENTION_ENFORCED=True)
@@ -115,10 +121,12 @@ class TestEventsRetentionAPI(APIBaseTest):
self._set_membership(level)
OrganizationEventsRetentionConfig.objects.create(organization=self.organization, min_events_retention_months=6)
- response = self.client.post(self.url(), {"retention_months": months}, format="json")
+ with patch("posthoganalytics.capture") as capture, self.captureOnCommitCallbacks(execute=True):
+ response = self.client.post(self.url(), {"retention_months": months}, format="json")
assert response.status_code == expected_status
assert not TeamEventsRetentionConfig.objects.filter(team=self.team).exists()
+ assert not any(call.kwargs.get("event") == "events retention set" for call in capture.call_args_list)
def test_organization_admin_sets_and_clears_the_default_window(self) -> None:
self._set_membership("organization_admin")
@@ -153,9 +161,11 @@ class TestEventsRetentionAPI(APIBaseTest):
self._set_membership(level)
OrganizationEventsRetentionConfig.objects.create(organization=self.organization, max_events_retention_months=12)
- response = self.client.post(self.organization_url(), {"retention_months": months}, format="json")
+ with patch("posthoganalytics.capture") as capture, self.captureOnCommitCallbacks(execute=True):
+ response = self.client.post(self.organization_url(), {"retention_months": months}, format="json")
assert response.status_code == expected_status
+ assert not any(call.kwargs.get("event") == "events retention set" for call in capture.call_args_list)
assert (
OrganizationEventsRetentionConfig.objects.get(
organization=self.organization
@@ -187,3 +197,134 @@ class TestEventsRetentionAPI(APIBaseTest):
response = getattr(self.client, method)(url, {"retention_months": 1})
assert response.status_code == status.HTTP_405_METHOD_NOT_ALLOWED
+
+ @parameterized.expand(
+ [(scope, source) for scope in ("project", "organization") for source in ("web", "api", "mcp")]
+ )
+ def test_tracks_saved_retention_changes(self, scope: str, source: str) -> None:
+ self._set_membership("organization_admin")
+ url = self.url() if scope == "project" else self.organization_url()
+ headers = {}
+ if source == "api":
+ self.client.logout()
+ self.client.force_authenticate(user=self.user)
+ elif source == "mcp":
+ headers = {
+ "HTTP_X_POSTHOG_CLIENT": "mcp",
+ "HTTP_X_POSTHOG_MCP_SESSION_ID": "test-mcp-session",
+ "HTTP_X_POSTHOG_MCP_CONVERSATION_ID": "test-mcp-conversation",
+ "HTTP_X_POSTHOG_TRACE_ID": "test-ai-trace",
+ }
+
+ self.client.credentials(**headers)
+ with patch("posthoganalytics.capture") as capture:
+ for before, after in [(None, 6), (6, 12), (12, None)]:
+ capture.reset_mock()
+ with self.captureOnCommitCallbacks(execute=True):
+ response = self.client.post(url, {"retention_months": after}, format="json")
+ assert response.status_code == status.HTTP_200_OK
+ events = [
+ call.kwargs for call in capture.call_args_list if call.kwargs.get("event") == "events retention set"
+ ]
+ assert len(events) == 1
+ event = events[0]
+ assert event["distinct_id"] == self.user.distinct_id
+ assert event["groups"]["organization"] == str(self.organization.id)
+ assert event["properties"]["source"] == source
+ assert event["properties"]["scope"] == scope
+ assert event["properties"]["retention_months"] == after
+ assert event["properties"]["previous_retention_months"] == before
+ assert event["properties"]["organization_id"] == str(self.organization.id)
+ if scope == "project":
+ assert event["properties"]["project_id"] == self.team.id
+ if source == "mcp":
+ assert event["properties"]["$mcp_session_id"] == "test-mcp-session"
+ assert event["properties"]["$mcp_conversation_id"] == "test-mcp-conversation"
+ assert event["properties"]["$ai_trace_id"] == "test-ai-trace"
+ else:
+ assert "$mcp_session_id" not in event["properties"]
+ assert "$ai_trace_id" not in event["properties"]
+
+ capture.reset_mock()
+ with self.captureOnCommitCallbacks(execute=True):
+ response = self.client.post(url, {"retention_months": after}, format="json")
+ assert response.status_code == status.HTTP_200_OK
+ assert not any(call.kwargs.get("event") == "events retention set" for call in capture.call_args_list)
+
+ @parameterized.expand([("project",), ("organization",)])
+ def test_saves_retention_with_malformed_analytics_headers(self, scope: str) -> None:
+ self._set_membership("organization_admin")
+ url = self.url() if scope == "project" else self.organization_url()
+
+ with patch("posthoganalytics.capture"), self.captureOnCommitCallbacks(execute=True):
+ response = self.client.post(url, {"retention_months": 6}, format="json", HTTP_REFERER="https://[")
+
+ assert response.status_code == status.HTTP_200_OK
+ assert response.json()[f"{scope}_retention_months"] == 6
+
+ @parameterized.expand([("project",), ("organization",)])
+ def test_does_not_track_rolled_back_retention_changes(self, scope: str) -> None:
+ self._set_membership("organization_admin")
+ url = self.url() if scope == "project" else self.organization_url()
+
+ with patch("posthoganalytics.capture") as capture, self.captureOnCommitCallbacks(execute=True):
+ with transaction.atomic():
+ response = self.client.post(url, {"retention_months": 6}, format="json")
+ assert response.status_code == status.HTTP_200_OK
+ assert not any(call.kwargs.get("event") == "events retention set" for call in capture.call_args_list)
+ transaction.set_rollback(True)
+
+ assert not any(call.kwargs.get("event") == "events retention set" for call in capture.call_args_list)
+
+ @parameterized.expand(
+ [(scope, source) for scope in ("project", "organization") for source in ("mcp", "invalid", 42)]
+ )
+ def test_sanitizes_retention_analytics_properties(self, scope: str, source: str | int) -> None:
+ properties: dict[str, object] = {
+ "source": source,
+ "$mcp_session_id": " \x00session\n ",
+ "$mcp_conversation_id": {"id": "invalid"},
+ "$ai_trace_id": "t" * 2000,
+ "$session_id": 42,
+ "mcp_client_name": " \rclient\x7f ",
+ "was_impersonated": True,
+ "scope": "invalid",
+ "organization_id": "invalid",
+ "project_id": -1,
+ "retention_months": 1200,
+ "previous_retention_months": 1200,
+ "$set": {"email": "[email protected]"},
+ "unexpected_property": "invalid",
+ }
+
+ with patch("posthoganalytics.capture") as capture, self.captureOnCommitCallbacks(execute=True):
+ if scope == "project":
+ set_project_events_retention(
+ self.team, 6, user=self.user, was_impersonated=False, analytics_properties=properties
+ )
+ else:
+ set_organization_events_retention(
+ self.organization, 6, user=self.user, was_impersonated=False, analytics_properties=properties
+ )
+ properties["$ai_trace_id"] = "changed after save"
+
+ events = [call.kwargs for call in capture.call_args_list if call.kwargs.get("event") == "events retention set"]
+ assert len(events) == 1
+ captured = events[0]["properties"]
+ assert captured["source"] == ("mcp" if source == "mcp" else "unknown")
+ assert captured["$mcp_session_id"] == "session"
+ assert captured["$ai_trace_id"] == "t" * 1000
+ assert captured["mcp_client_name"] == "client"
+ assert captured["scope"] == scope
+ assert captured["organization_id"] == str(self.organization.id)
+ assert captured["retention_months"] == 6
+ assert captured["previous_retention_months"] is None
+ assert captured["was_impersonated"] is False
+ assert "$mcp_conversation_id" not in captured
+ assert "$session_id" not in captured
+ assert "$set" not in captured
+ assert "unexpected_property" not in captured
+ if scope == "project":
+ assert captured["project_id"] == self.team.id
+ else:
+ assert "project_id" not in captured