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(workflows): audit email sending tier changes in the activity log (#100947)

Luke Belton3570c91ef52b
diff --git a/docs/internal/workflows-email-sending-tiers.md b/docs/internal/workflows-email-sending-tiers.md
index 6914badeaa51..73e358d91950 100644
--- a/docs/internal/workflows-email-sending-tiers.md
+++ b/docs/internal/workflows-email-sending-tiers.md
@@ -12,6 +12,7 @@ Only workflows that send email are subject to the tiers; SMS, push, and webhook
- Batch audience cap: `get_hogflow_batch_trigger_limit` in `products/workflows/backend/utils/batch_trigger_limit.py`, applied at batch dispatch and shown in the blast radius preview.
- Send-time caps: two Valkey token buckets per team in the CDP email worker (`claimTeamSendingBudget` in `nodejs/src/cdp/services/messaging/email.service.ts`).
- Staff controls: the team's Django admin page (view state, set/pin a tier, recompute now).
+- Audit trail: every tier or pin change writes an `email_sending_tier_changed` row to the team's activity log, with the before and after values and the decision reason (`staff_set` for a tier staff set by hand). Staff rows name the acting user. Sweep and backfill rows carry a trigger with the job type and a per-run id. The rows are staff-only in the activity log (`products/workflows/backend/services/email_sending_tier_audit.py`).
- Customer surface: the Reputation tab's sending allowance card, shown only while the team is enforced.
## Configuration
diff --git a/frontend/src/lib/components/ActivityLog/humanizeActivity.test.tsx b/frontend/src/lib/components/ActivityLog/humanizeActivity.test.tsx
index 25a7a16d2c25..bffb44378702 100644
--- a/frontend/src/lib/components/ActivityLog/humanizeActivity.test.tsx
+++ b/frontend/src/lib/components/ActivityLog/humanizeActivity.test.tsx
@@ -168,6 +168,48 @@ describe('humanizeActivity', () => {
}
})
+ it.each<{ reason: string; changes: Partial<ActivityChange>[]; action: string; description: string }>([
+ {
+ reason: 'staff_set',
+ changes: [
+ { field: 'email_sending_tier', before: 2, after: 3 },
+ { field: 'email_sending_tier_pinned', before: false, after: true },
+ ],
+ action: 'Set the workflow email sending tier from 2 to 3 and pinned it there',
+ description: 'A user set the workflow email sending tier on Example from 2 to 3 and pinned it there',
+ },
+ {
+ reason: 'clean_and_used',
+ changes: [{ field: 'email_sending_tier', before: 1, after: 2 }],
+ action: 'Moved the workflow email sending tier from 1 to 2',
+ description: 'A user moved the workflow email sending tier on Example from 1 to 2 (reason: clean_and_used)',
+ },
+ {
+ reason: 'staff_set',
+ changes: [{ field: 'email_sending_tier_pinned', before: true, after: false }],
+ action: 'Unpinned the workflow email sending tier',
+ description: 'A user unpinned the workflow email sending tier on Example',
+ },
+ ])('describes an email sending tier change: $action', ({ reason, changes, action, description }) => {
+ const logItem = makeLogItem({
+ scope: ActivityScope.TEAM,
+ activity: 'email_sending_tier_changed',
+ detail: {
+ merge: null,
+ trigger: null,
+ name: 'Example',
+ context: { reason },
+ changes: changes.map((change) => ({ type: ActivityScope.TEAM, action: 'changed', ...change })),
+ },
+ })
+ const result = teamActivityDescriber(logItem)
+ const text = (value: Description | undefined): string =>
+ (render(<>{value}</>).container.textContent || '').replace(/\s+/g, ' ').trim()
+
+ expect(text(result.description)).toBe(description)
+ expect(text(result.summary?.action)).toBe(action)
+ })
+
it.each([
['minted', 'A user created Developer mode token for [email protected]'],
['revoked', 'A user revoked Developer mode token for [email protected]'],
diff --git a/frontend/src/scenes/team-activity/teamActivityDescriber.tsx b/frontend/src/scenes/team-activity/teamActivityDescriber.tsx
index f491a1405671..b03e9b40c018 100644
--- a/frontend/src/scenes/team-activity/teamActivityDescriber.tsx
+++ b/frontend/src/scenes/team-activity/teamActivityDescriber.tsx
@@ -16,7 +16,7 @@ import PropertyFiltersDisplay from 'lib/components/PropertyFilters/components/Pr
import { Link } from 'lib/lemon-ui/Link'
import { CURRENCY_SYMBOL_TO_EMOJI_MAP, CURRENCY_SYMBOL_TO_NAME_MAP } from 'lib/utils/currency'
import { isObject } from 'lib/utils/guards'
-import { pluralize } from 'lib/utils/strings'
+import { capitalizeFirstLetter, pluralize } from 'lib/utils/strings'
import { ExperimentsConfig } from 'scenes/settings/environment/experimentsConfigLogic'
import { urls } from 'scenes/urls'
@@ -868,6 +868,33 @@ function describeWorkflowEmailSuspension(logItem: ActivityLogItem): HumanizedCha
}
}
+function describeWorkflowEmailTierChange(logItem: ActivityLogItem): HumanizedChange {
+ const changes = logItem.detail?.changes || []
+ const tierChange = changes.find((change) => change.field === 'email_sending_tier')
+ const pinChange = changes.find((change) => change.field === 'email_sending_tier_pinned')
+ const contextReason = logItem.detail?.context?.reason as string | undefined
+ // A staff-set tier has no decision behind it, so the row says "set" and shows no reason.
+ const setByStaff = contextReason === 'staff_set'
+ const reason = setByStaff ? undefined : contextReason
+ const target = shortIdActivityLink(logItem, urls.notebook)
+ const pinVerb = pinChange ? (pinChange.after ? 'pinned' : 'unpinned') : null
+ const verb = tierChange ? (setByStaff ? 'set' : 'moved') : (pinVerb ?? 'changed')
+ const tierMove = tierChange ? ` from ${String(tierChange.before)} to ${String(tierChange.after)}` : ''
+ const pinSuffix = tierChange && pinVerb ? ` and ${pinVerb === 'pinned' ? 'pinned it there' : 'unpinned it'}` : ''
+ const action = `${verb} the workflow email sending tier`
+ return {
+ summary: activityLogSummary(logItem, `${capitalizeFirstLetter(action)}${tierMove}${pinSuffix}`, target, reason),
+ description: (
+ <>
+ <ActivityLogUserName logItem={logItem} /> {action} on {target}
+ {tierMove}
+ {pinSuffix}
+ {reason ? <> (reason: {reason})</> : null}
+ </>
+ ),
+ }
+}
+
export function teamActivityDescriber(logItem: ActivityLogItem, asNotification?: boolean): HumanizedChange {
if (logItem.scope !== ActivityScope.TEAM) {
console.error('team describer received a non-Team activity')
@@ -878,6 +905,10 @@ export function teamActivityDescriber(logItem: ActivityLogItem, asNotification?:
return describeWorkflowEmailSuspension(logItem)
}
+ if (logItem.activity === 'email_sending_tier_changed') {
+ return describeWorkflowEmailTierChange(logItem)
+ }
+
if (logItem.activity == 'changed' || logItem.activity == 'updated') {
const changes = describeMappedChanges(
logItem,
diff --git a/posthog/admin/admins/team_admin.py b/posthog/admin/admins/team_admin.py
index a1835e0f0bc7..402bc27a4a8a 100644
--- a/posthog/admin/admins/team_admin.py
+++ b/posthog/admin/admins/team_admin.py
@@ -7,7 +7,7 @@ import hashlib
import dataclasses
from datetime import UTC, datetime, timedelta
from decimal import Decimal, InvalidOperation
-from typing import Any
+from typing import Any, cast
from urllib import parse
from django.conf import settings
@@ -36,7 +36,7 @@ from posthog.admin.inlines.team_experiments_config_inline import TeamExperiments
from posthog.admin.inlines.team_marketing_analytics_config_inline import TeamMarketingAnalyticsConfigInline
from posthog.helpers.impersonation import is_impersonated
from posthog.llm.gateway_internal_client import AIGatewayInternalError, AIGatewayNotConfigured, add_credit, get_wallet
-from posthog.models import Team
+from posthog.models import Team, User
from posthog.models.activity_logging.activity_log import ActivityContextBase, ActivityLog, Detail, log_activity
from posthog.models.events_retention_config import (
OrganizationEventsRetentionConfig,
@@ -839,7 +839,9 @@ class TeamAdmin(admin.ModelAdmin):
# The facade row-locks the config while checking + flipping, so concurrent submits can't
# both dispatch the customer email + notification. Side effects stay outside that lock.
- change = suspend_email_sending(team.pk, reason)
+ change = suspend_email_sending(
+ team.pk, reason, user_id=cast(User, request.user).pk, was_impersonated=is_impersonated(request)
+ )
already_suspended_at = change.previously_suspended_at
suspended_at = change.changed_at
@@ -1036,7 +1038,13 @@ class TeamAdmin(admin.ModelAdmin):
return redirect(team_url)
pinned = request.POST.get("pinned") == "on"
- previous_tier = set_email_sending_tier(team.pk, tier=tier, pinned=pinned)
+ previous_tier = set_email_sending_tier(
+ team.pk,
+ tier=tier,
+ pinned=pinned,
+ user_id=cast(User, request.user).pk,
+ was_impersonated=is_impersonated(request),
+ )
logger.info(
"admin_set_email_sending_tier",
@@ -1070,7 +1078,9 @@ class TeamAdmin(admin.ModelAdmin):
# suspend and set-tier actions.
ensure_workflows_config(team.pk)
try:
- decision = recompute_email_sending_tier(team.id)
+ decision = recompute_email_sending_tier(
+ team.id, user_id=cast(User, request.user).pk, was_impersonated=is_impersonated(request)
+ )
except Exception:
logger.exception("admin_recompute_email_sending_tier_failed", team_id=team.id)
self.message_user(request, "Could not recompute the tier. Check the logs.", level=messages.ERROR)
diff --git a/posthog/admin/test_team_admin.py b/posthog/admin/test_team_admin.py
index b45e0d71bbff..2723fed59760 100644
--- a/posthog/admin/test_team_admin.py
+++ b/posthog/admin/test_team_admin.py
@@ -25,7 +25,6 @@ from posthog.llm.gateway_internal_client import (
)
from posthog.models import Organization
from posthog.models.activity_logging.activity_log import ActivityLog
-from posthog.models.team.extensions import get_or_create_team_extension
from posthog.models.team.team import Team
from posthog.personhog_client.fake_client import FakePersonHogClient
from posthog.personhog_client.proto import GetGroupTypeMappingsByProjectIdRequest
@@ -680,8 +679,8 @@ class TestTeamAdminEmailSendingSuspension(BaseTest):
assert self.mock_notification.call_count == 1
def test_suspend_drops_the_tier_to_zero_even_when_pinned(self) -> None:
- config = get_or_create_team_extension(
- self.team, TeamWorkflowsConfig, defaults={"email_sending_tier": 3, "email_sending_tier_pinned": True}
+ config, _ = TeamWorkflowsConfig.objects.update_or_create(
+ team=self.team, defaults={"email_sending_tier": 3, "email_sending_tier_pinned": True}
)
response = self.admin.suspend_email_sending_view(self._post({"reason": "spam complaints"}), str(self.team.pk))
@@ -692,6 +691,39 @@ class TestTeamAdminEmailSendingSuspension(BaseTest):
assert config.email_sending_tier == 0
assert config.email_sending_tier_updated_at is not None
+ entry = ActivityLog.objects.get(scope="Team", team_id=self.team.id, activity="email_sending_tier_changed")
+ assert entry.user == self.user
+ assert (entry.detail or {})["context"] == {"reason": "staff_suspension"}
+
+ @parameterized.expand(
+ [
+ ("tier_change", {"tier": "2"}, [("email_sending_tier", 1, 2)]),
+ ("pin_only", {"tier": "1", "pinned": "on"}, [("email_sending_tier_pinned", False, True)]),
+ ("no_change", {"tier": "1"}, None),
+ ]
+ )
+ def test_set_tier_audits_what_changed(
+ self, _name: str, form: dict[str, str], expected_changes: list[tuple[str, object, object]] | None
+ ) -> None:
+ TeamWorkflowsConfig.objects.update_or_create(
+ team=self.team, defaults={"email_sending_tier": 1, "email_sending_tier_pinned": False}
+ )
+
+ response = self.admin.set_email_sending_tier_view(self._post(form), str(self.team.pk))
+ assert response.status_code == 302
+
+ entries = list(
+ ActivityLog.objects.filter(scope="Team", team_id=self.team.id, activity="email_sending_tier_changed")
+ )
+ if expected_changes is None:
+ assert entries == []
+ return
+ assert len(entries) == 1
+ assert entries[0].user == self.user
+ detail = entries[0].detail or {}
+ assert detail["context"] == {"reason": "staff_set"}
+ assert [(c["field"], c["before"], c["after"]) for c in detail["changes"]] == expected_changes
+
def test_tier_actions_render_without_a_nested_form(self) -> None:
# The field renders inside the admin's team change form. A nested <form> would break the page,
# so the actions must submit the surrounding form through formaction instead.
@@ -732,7 +764,7 @@ class TestTeamAdminEmailSendingSuspension(BaseTest):
with patch("posthog.admin.admins.team_admin.recompute_email_sending_tier", return_value=None) as mock_recompute:
response = self.admin.recompute_email_sending_tier_view(self._post(), str(self.team.pk))
assert response.status_code == 302
- mock_recompute.assert_called_once_with(self.team.id)
+ mock_recompute.assert_called_once_with(self.team.id, user_id=self.user.pk, was_impersonated=False)
assert self._config() is not None
def test_suspend_is_idempotent(self) -> None:
diff --git a/posthog/api/project.py b/posthog/api/project.py
index e52ce6ae7240..19014ebe0f3f 100644
--- a/posthog/api/project.py
+++ b/posthog/api/project.py
@@ -2079,6 +2079,7 @@ class ProjectViewSet(
item_ids=[str(project.pk)],
limit=page_params.limit,
page=page_params.page,
+ user=request.user,
)
return activity_page_response(activity_page, page_params.limit, page_params.page, request)
diff --git a/posthog/api/team/viewsets.py b/posthog/api/team/viewsets.py
index 112b861d762b..7b47d43bfdf3 100644
--- a/posthog/api/team/viewsets.py
+++ b/posthog/api/team/viewsets.py
@@ -433,6 +433,7 @@ class TeamViewSet(
item_ids=[str(team.pk)],
limit=page_params.limit,
page=page_params.page,
+ user=request.user,
)
return activity_page_response(activity_page, page_params.limit, page_params.page, request)
diff --git a/posthog/api/test/test_team.py b/posthog/api/test/test_team.py
index fc93166638d3..92e9808a6e1c 100644
--- a/posthog/api/test/test_team.py
+++ b/posthog/api/test/test_team.py
@@ -1191,6 +1191,27 @@ def team_api_test_factory():
self.assertEqual(response.status_code, status.HTTP_200_OK)
self.assertEqual(response.json(), {"is_generating_demo_data": False})
+ @parameterized.expand([("member", False, []), ("staff", True, ["email_sending_tier_changed"])])
+ def test_activity_hides_staff_only_rows_from_members(
+ self, _name: str, is_staff: bool, expected_activities: list[str]
+ ) -> None:
+ ActivityLog.objects.create(
+ team_id=self.team.pk,
+ organization_id=self.organization.id,
+ user=User.objects.create(email="[email protected]", is_staff=True),
+ scope="Team",
+ item_id=str(self.team.pk),
+ activity="email_sending_tier_changed",
+ detail={"name": self.team.name},
+ )
+ self.user.is_staff = is_staff
+ self.user.save()
+
+ response = self.client.get(f"/api/environments/{self.team.pk}/activity")
+
+ assert response.status_code == status.HTTP_200_OK, response.json()
+ assert [item["activity"] for item in response.json()["results"]] == expected_activities
+
@time_machine.travel("2022-02-08", tick=False)
def test_team_float_config_can_be_serialized_to_activity_log(self):
# regression test since this isn't true by default
diff --git a/posthog/models/activity_logging/activity_log.py b/posthog/models/activity_logging/activity_log.py
index f3f0f635455c..bfe63e3595e2 100644
--- a/posthog/models/activity_logging/activity_log.py
+++ b/posthog/models/activity_logging/activity_log.py
@@ -681,10 +681,11 @@ activity_visibility_restrictions: list[dict[str, Any]] = [
"allow_staff": True,
},
{
- # Staff-only email sending suspension flips: the acting staff user must not leak into the
- # org activity log. The customer is told via email and in-app notification instead.
+ # Staff-only email sending controls: the acting staff user must not leak into the org
+ # activity log. Suspensions and automatic tier moves reach the customer through email and
+ # in-app notification, and the Reputation tab shows the current tier.
"scope": "Team",
- "activities": ["email_sending_suspended", "email_sending_unsuspended"],
+ "activities": ["email_sending_suspended", "email_sending_unsuspended", "email_sending_tier_changed"],
"exclude_when": {},
"allow_staff": True,
},
@@ -1730,6 +1731,7 @@ def load_activity(
item_ids: Optional[list[str]] = None,
limit: int = 10,
page: int = 1,
+ user: Union["User", AnonymousUser, None] = None,
) -> ActivityPage:
# TODO in follow-up to posthog #8931 selecting specific fields into a return type from this query
@@ -1740,6 +1742,9 @@ def load_activity(
if item_ids is not None:
activity_query = activity_query.filter(item_id__in=item_ids)
+ if user is not None:
+ activity_query = apply_activity_visibility_restrictions(activity_query, user)
+
return get_activity_page(activity_query, limit, page)
diff --git a/products/workflows/backend/facade/api.py b/products/workflows/backend/facade/api.py
index 436294a9efa8..060614e43bb8 100644
--- a/products/workflows/backend/facade/api.py
+++ b/products/workflows/backend/facade/api.py
@@ -303,13 +303,15 @@ def team_has_active_workflows_using_cohorts(*, team_id: int) -> bool:
return team_has_active_hog_flows_mentioning_cohorts(team_id)
-def recompute_email_sending_tier(team_id: int) -> TierDecision | None:
+def recompute_email_sending_tier(
+ team_id: int, *, user_id: int | None = None, was_impersonated: bool = False
+) -> TierDecision | None:
# Deferred to keep the ClickHouse metrics client off the facade import path.
from products.workflows.backend.services.email_sending_tier import ( # noqa: PLC0415
recompute_email_sending_tier_for_team,
)
- return recompute_email_sending_tier_for_team(team_id)
+ return recompute_email_sending_tier_for_team(team_id, user_id=user_id, was_impersonated=was_impersonated)
# The provider helpers look the provider class up on the providers package at call time, which
diff --git a/products/workflows/backend/management/commands/backfill_workflows_email_sending_tiers.py b/products/workflows/backend/management/commands/backfill_workflows_email_sending_tiers.py
index 40433416a3d3..64f6518c0c88 100644
--- a/products/workflows/backend/management/commands/backfill_workflows_email_sending_tiers.py
+++ b/products/workflows/backend/management/commands/backfill_workflows_email_sending_tiers.py
@@ -2,6 +2,7 @@ from collections import Counter
from collections.abc import Iterable
from datetime import timedelta
from typing import Any, Optional
+from uuid import uuid4
from django.core.management.base import BaseCommand
from django.utils import timezone
@@ -9,6 +10,7 @@ from django.utils import timezone
import structlog
from posthog.clickhouse.client.connection import Workload
+from posthog.models.activity_logging.activity_log import Trigger
from posthog.models.team import Team
from posthog.models.team.extensions import get_or_create_team_extension
@@ -20,6 +22,10 @@ from products.workflows.backend.services.email_sending_tier import (
build_sending_histories,
decide_tier,
)
+from products.workflows.backend.services.email_sending_tier_audit import (
+ EMAIL_SENDING_TIER_BACKFILL_JOB_TYPE,
+ log_email_sending_tier_change,
+)
from products.workflows.backend.utils.email_sending_tiers import (
MIN_EMAIL_SENDING_TIER,
get_email_sending_tier_limits,
@@ -137,6 +143,7 @@ class Command(BaseCommand):
def _apply(self, decisions: list[TierDecision]) -> int:
teams = {team.id: team for team in Team.objects.filter(id__in=[d.team_id for d in decisions])}
now = timezone.now()
+ trigger = Trigger(job_type=EMAIL_SENDING_TIER_BACKFILL_JOB_TYPE, job_id=str(uuid4()), payload={})
written = 0
for decision in decisions:
team = teams.get(decision.team_id)
@@ -166,6 +173,13 @@ class Command(BaseCommand):
new_tier=decision.new_tier,
reason=decision.reason,
)
+ log_email_sending_tier_change(
+ team,
+ previous_tier=decision.previous_tier,
+ new_tier=decision.new_tier,
+ reason=decision.reason,
+ trigger=trigger,
+ )
return written
def _current_tiers(self, team_ids: Iterable[int]) -> dict[int, int]:
diff --git a/products/workflows/backend/services/email_sending_controls.py b/products/workflows/backend/services/email_sending_controls.py
index 7e2ee83153e0..6e7aaf197590 100644
--- a/products/workflows/backend/services/email_sending_controls.py
+++ b/products/workflows/backend/services/email_sending_controls.py
@@ -8,11 +8,14 @@ from posthog.models.team.extensions import get_or_create_team_extension
from products.workflows.backend.facade.contracts import EmailSendingState, EmailSendingSuspensionChange
from products.workflows.backend.models.team_workflows_config import TeamWorkflowsConfig
+from products.workflows.backend.services.email_sending_tier_audit import log_email_sending_tier_change
from products.workflows.backend.utils.email_sending_tiers import MIN_EMAIL_SENDING_TIER
-def ensure_workflows_config(team_id: int) -> None:
- get_or_create_team_extension(Team.objects.get(pk=team_id), TeamWorkflowsConfig)
+def ensure_workflows_config(team_id: int) -> Team:
+ team = Team.objects.get(pk=team_id)
+ get_or_create_team_extension(team, TeamWorkflowsConfig)
+ return team
def get_email_sending_state(team_id: int) -> EmailSendingState | None:
@@ -28,17 +31,20 @@ def get_email_sending_state(team_id: int) -> EmailSendingState | None:
)
-def suspend_email_sending(team_id: int, reason: str) -> EmailSendingSuspensionChange:
+def suspend_email_sending(
+ team_id: int, reason: str, *, user_id: int | None = None, was_impersonated: bool = False
+) -> EmailSendingSuspensionChange:
# Row-lock the config while checking + flipping so two concurrent submits (retried POST,
# two open admin tabs) can't both pass the idempotency check and both dispatch the
# customer email + notification. Side effects stay with the caller, outside the atomic block.
- ensure_workflows_config(team_id)
+ team = ensure_workflows_config(team_id)
with transaction.atomic():
config = TeamWorkflowsConfig.objects.select_for_update().get(team_id=team_id)
if config.email_sending_suspended_at is not None:
return EmailSendingSuspensionChange(
changed_at=None, previously_suspended_at=config.email_sending_suspended_at
)
+ previous_tier = config.email_sending_tier
suspended_at = timezone.now()
config.email_sending_suspended_at = suspended_at
config.email_sending_suspension_reason = reason
@@ -58,6 +64,14 @@ def suspend_email_sending(team_id: int, reason: str) -> EmailSendingSuspensionCh
"email_sending_tier_updated_at",
]
)
+ log_email_sending_tier_change(
+ team,
+ previous_tier=previous_tier,
+ new_tier=MIN_EMAIL_SENDING_TIER,
+ reason="staff_suspension",
+ user_id=user_id,
+ was_impersonated=was_impersonated,
+ )
return EmailSendingSuspensionChange(changed_at=suspended_at)
@@ -75,12 +89,15 @@ def unsuspend_email_sending(team_id: int) -> EmailSendingSuspensionChange:
return EmailSendingSuspensionChange(changed_at=unsuspended_at)
-def set_email_sending_tier(team_id: int, *, tier: int, pinned: bool) -> int:
+def set_email_sending_tier(
+ team_id: int, *, tier: int, pinned: bool, user_id: int | None = None, was_impersonated: bool = False
+) -> int:
"""Write a staff-chosen tier and pin state, and return the tier the team had before."""
- ensure_workflows_config(team_id)
+ team = ensure_workflows_config(team_id)
with transaction.atomic():
config = TeamWorkflowsConfig.objects.select_for_update().get(team_id=team_id)
previous_tier = config.email_sending_tier
+ previous_pinned = config.email_sending_tier_pinned
config.email_sending_tier = tier
config.email_sending_tier_pinned = pinned
if tier != previous_tier:
@@ -94,4 +111,13 @@ def set_email_sending_tier(team_id: int, *, tier: int, pinned: bool) -> int:
"email_sending_tier_updated_at",
]
)
+ log_email_sending_tier_change(
+ team,
+ previous_tier=previous_tier,
+ new_tier=tier,
+ reason="staff_set",
+ pin_change=(previous_pinned, pinned),
+ user_id=user_id,
+ was_impersonated=was_impersonated,
+ )
return previous_tier
diff --git a/products/workflows/backend/services/email_sending_tier.py b/products/workflows/backend/services/email_sending_tier.py
index 4f3b83feae6b..5a0e0dabeca6 100644
--- a/products/workflows/backend/services/email_sending_tier.py
+++ b/products/workflows/backend/services/email_sending_tier.py
@@ -10,9 +10,11 @@ from posthog.api.app_metrics2 import fetch_app_metric_daily_totals_by_team
from posthog.clickhouse.client.connection import Workload
from posthog.clickhouse.query_tagging import Feature, Product, tags_context
from posthog.dataclasses import frozen
+from posthog.models.activity_logging.activity_log import Trigger
from products.workflows.backend.facade.contracts import TierDecision
from products.workflows.backend.models.team_workflows_config import TeamWorkflowsConfig
+from products.workflows.backend.services.email_sending_tier_audit import log_email_sending_tier_change
from products.workflows.backend.utils.email_sending_tiers import (
MIN_EMAIL_SENDING_TIER,
get_email_sending_tier_limits,
@@ -364,7 +366,14 @@ def _empty_history(team_id: int) -> TeamSendingHistory:
return TeamSendingHistory(team_id=team_id, sent=0, hard_bounced=0, complained=0, auto_paused=False, daily_sends={})
-def apply_tier_decision(config: TeamWorkflowsConfig, decision: TierDecision) -> bool:
+def apply_tier_decision(
+ config: TeamWorkflowsConfig,
+ decision: TierDecision,
+ *,
+ trigger: Trigger | None = None,
+ user_id: int | None = None,
+ was_impersonated: bool = False,
+) -> bool:
"""Persist a tier change. Returns whether anything was written."""
if not decision.changed:
return False
@@ -399,10 +408,25 @@ def apply_tier_decision(config: TeamWorkflowsConfig, decision: TierDecision) ->
new_tier=decision.new_tier,
reason=decision.reason,
)
+ log_email_sending_tier_change(
+ config.team,
+ previous_tier=decision.previous_tier,
+ new_tier=decision.new_tier,
+ reason=decision.reason,
+ trigger=trigger,
+ user_id=user_id,
+ was_impersonated=was_impersonated,
+ )
return True
-def recompute_email_sending_tiers(team_ids: Optional[list[int]] = None) -> list[TierDecision]:
+def recompute_email_sending_tiers(
+ team_ids: Optional[list[int]] = None,
+ *,
+ trigger: Trigger | None = None,
+ user_id: int | None = None,
+ was_impersonated: bool = False,
+) -> list[TierDecision]:
"""
Move every candidate team at most one tier, up or down.
@@ -433,7 +457,8 @@ def recompute_email_sending_tiers(team_ids: Optional[list[int]] = None) -> list[
# select_related bypasses TeamManager's defer, so without only() the join pulls every wide Team
# column, including the deprecated taxonomy blobs, for every candidate. The decision reads only
- # created_at from Team, so restrict the load to that plus the config fields it uses.
+ # created_at from Team and the audit row reads name and organization, so restrict the load to
+ # those plus the config fields it uses.
configs = {
config.team_id: config
for config in TeamWorkflowsConfig.objects.filter(team_id__in=candidate_ids)
@@ -447,6 +472,8 @@ def recompute_email_sending_tiers(team_ids: Optional[list[int]] = None) -> list[
"ses_tenant_sending_status",
"ses_tenant_reputation_impact",
"team__created_at",
+ "team__name",
+ "team__organization_id",
)
}
@@ -472,17 +499,21 @@ def recompute_email_sending_tiers(team_ids: Optional[list[int]] = None) -> list[
),
last_rate_demotion_at=config.email_sending_tier_demoted_at,
)
- if not decision.changed or apply_tier_decision(config, decision):
+ if not decision.changed or apply_tier_decision(
+ config, decision, trigger=trigger, user_id=user_id, was_impersonated=was_impersonated
+ ):
decisions.append(decision)
return decisions
-def recompute_email_sending_tier_for_team(team_id: int) -> Optional[TierDecision]:
+def recompute_email_sending_tier_for_team(
+ team_id: int, *, user_id: int | None = None, was_impersonated: bool = False
+) -> Optional[TierDecision]:
"""
Recompute one team now, so a staff suspension takes its tier down without waiting for the
next periodic run. Returns the decision, held or applied, so the caller can say why a team
did not move. None means the team was not evaluated at all: it is pinned, it has no config
row, or its state changed while recomputing.
"""
- decisions = recompute_email_sending_tiers(team_ids=[team_id])
+ decisions = recompute_email_sending_tiers(team_ids=[team_id], user_id=user_id, was_impersonated=was_impersonated)
return decisions[0] if decisions else None
diff --git a/products/workflows/backend/services/email_sending_tier_audit.py b/products/workflows/backend/services/email_sending_tier_audit.py
new file mode 100644
index 000000000000..5be490d4166f
--- /dev/null
+++ b/products/workflows/backend/services/email_sending_tier_audit.py
@@ -0,0 +1,64 @@
+"""Activity log rows for workflow email sending tier and pin changes."""
+
+import dataclasses
+
+from posthog.models.activity_logging.activity_log import ActivityContextBase, Change, Detail, Trigger, log_activity
+from posthog.models.team import Team
+from posthog.models.user import User
+
+EMAIL_SENDING_TIER_CHANGED_ACTIVITY = "email_sending_tier_changed"
+EMAIL_SENDING_TIER_SWEEP_JOB_TYPE = "workflows_email_sending_tier_sweep"
+EMAIL_SENDING_TIER_BACKFILL_JOB_TYPE = "backfill_workflows_email_sending_tiers"
+
+
[email protected](frozen=True)
+class EmailSendingTierActivityContext(ActivityContextBase):
+ # The decision reason for a computed change, or staff_set for a tier staff set by hand.
+ reason: str
+
+
+def log_email_sending_tier_change(
+ team: Team,
+ *,
+ previous_tier: int,
+ new_tier: int,
+ reason: str,
+ pin_change: tuple[bool, bool] | None = None,
+ trigger: Trigger | None = None,
+ user_id: int | None = None,
+ was_impersonated: bool = False,
+) -> None:
+ """Write the audit row for a tier or pin change. Writes nothing when neither value moved."""
+ changes: list[Change] = []
+ if previous_tier != new_tier:
+ changes.append(
+ Change(type="Team", action="changed", field="email_sending_tier", before=previous_tier, after=new_tier)
+ )
+ if pin_change is not None and pin_change[0] != pin_change[1]:
+ changes.append(
+ Change(
+ type="Team",
+ action="changed",
+ field="email_sending_tier_pinned",
+ before=pin_change[0],
+ after=pin_change[1],
+ )
+ )
+ if not changes:
+ return
+
+ log_activity(
+ organization_id=team.organization_id,
+ team_id=team.id,
+ user=User.objects.filter(pk=user_id).first() if user_id is not None else None,
+ was_impersonated=was_impersonated,
+ item_id=team.id,
+ scope="Team",
+ activity=EMAIL_SENDING_TIER_CHANGED_ACTIVITY,
+ detail=Detail(
+ name=team.name,
+ changes=changes,
+ trigger=trigger,
+ context=EmailSendingTierActivityContext(reason=reason),
+ ),
+ )
diff --git a/products/workflows/backend/tasks/email_sending_tiers.py b/products/workflows/backend/tasks/email_sending_tiers.py
index e6fb41a11210..abbade369893 100644
--- a/products/workflows/backend/tasks/email_sending_tiers.py
+++ b/products/workflows/backend/tasks/email_sending_tiers.py
@@ -1,9 +1,13 @@
+from uuid import uuid4
+
import structlog
from celery import shared_task
+from posthog.models.activity_logging.activity_log import Trigger
from posthog.tasks.utils import CeleryQueue
from products.workflows.backend.services.email_sending_tier import recompute_email_sending_tiers
+from products.workflows.backend.services.email_sending_tier_audit import EMAIL_SENDING_TIER_SWEEP_JOB_TYPE
from products.workflows.backend.services.email_sending_tier_notifications import notify_email_sending_tier_changes
logger = structlog.get_logger(__name__)
@@ -14,7 +18,10 @@ def recompute_workflows_email_sending_tiers() -> None:
"""Move each team at most one trust tier, based on how much workflow email it sent and how
clean the sending was. Runs in every rollout mode: tiers are stored before anything reads them,
so enforcement can be switched on against a settled distribution."""
- decisions = recompute_email_sending_tiers()
+ # One job id groups every audit row this run writes.
+ decisions = recompute_email_sending_tiers(
+ trigger=Trigger(job_type=EMAIL_SENDING_TIER_SWEEP_JOB_TYPE, job_id=str(uuid4()), payload={})
+ )
notify_email_sending_tier_changes(decisions)
logger.info(
"workflows_email_sending_tier_sweep_finished",
diff --git a/products/workflows/backend/test/test_email_sending_tier.py b/products/workflows/backend/test/test_email_sending_tier.py
index 6509c8d0b0d4..21a1d1490b02 100644
--- a/products/workflows/backend/test/test_email_sending_tier.py
+++ b/products/workflows/backend/test/test_email_sending_tier.py
@@ -8,6 +8,8 @@ from django.utils import timezone
from parameterized import parameterized
+from posthog.models.activity_logging.activity_log import ActivityLog
+
from products.workflows.backend.management.commands.backfill_workflows_email_sending_tiers import (
Command as BackfillCommand,
)
@@ -20,8 +22,10 @@ from products.workflows.backend.services.email_sending_tier import (
apply_tier_decision,
decide_tier,
highest_qualifying_tier,
+ recompute_email_sending_tier_for_team,
recompute_email_sending_tiers,
)
+from products.workflows.backend.tasks.email_sending_tiers import recompute_workflows_email_sending_tiers
from products.workflows.backend.utils.email_sending_tiers import get_email_sending_tier_limits
TIER_HOURLY_CAPS = [200, 600, 2000, 6000, 20000, 60000, 200000]
@@ -395,17 +399,36 @@ class TestRecomputeEmailSendingTiers(BaseTest):
assert not held.changed
assert held.reason == "tier_not_used_enough"
assert TeamWorkflowsConfig.objects.get(team=self.team).email_sending_tier == 2
+ assert not ActivityLog.objects.filter(scope="Team", activity="email_sending_tier_changed").exists()
- def test_promotion_is_persisted_with_a_fresh_timestamp(self) -> None:
+ @parameterized.expand([("sweep", False, "workflows_email_sending_tier_sweep"), ("admin_recompute", True, None)])
+ def test_promotion_is_persisted_with_a_fresh_timestamp_and_audited(
+ self, _name: str, by_staff: bool, expected_job_type: str | None
+ ) -> None:
self._config(email_sending_tier=0, email_sending_tier_updated_at=timezone.now() - timedelta(days=30))
used = clean_days(2, TIER_DAILY_CAPS[0])
- self._run({self.team.id: history(team_id=self.team.id, sent=sum(used.values()), daily_sends=used)})
+ histories = {self.team.id: history(team_id=self.team.id, sent=sum(used.values()), daily_sends=used)}
+ with patch(
+ "products.workflows.backend.services.email_sending_tier.build_sending_history_windows",
+ return_value=SendingHistoryWindows(window=histories, recent=histories),
+ ):
+ if by_staff:
+ recompute_email_sending_tier_for_team(self.team.id, user_id=self.user.pk)
+ else:
+ recompute_workflows_email_sending_tiers()
config = TeamWorkflowsConfig.objects.get(team=self.team)
assert config.email_sending_tier == 1
assert config.email_sending_tier_updated_at is not None
assert config.email_sending_tier_updated_at > timezone.now() - timedelta(minutes=1)
+ entry = ActivityLog.objects.get(scope="Team", team_id=self.team.id, activity="email_sending_tier_changed")
+ assert entry.user == (self.user if by_staff else None)
+ detail = entry.detail or {}
+ assert detail["context"] == {"reason": "clean_and_used"}
+ assert (detail["trigger"] or {}).get("job_type") == expected_job_type
+ assert [(c["field"], c["before"], c["after"]) for c in detail["changes"]] == [("email_sending_tier", 0, 1)]
+
def test_suspended_team_is_demoted_even_with_no_recent_sending(self) -> None:
self._config(
email_sending_tier=3,
@@ -431,6 +454,7 @@ class TestRecomputeEmailSendingTiers(BaseTest):
decision = TierDecision(team_id=self.team.id, previous_tier=1, new_tier=2, reason="clean_and_used")
assert apply_tier_decision(config, decision) is False
assert TeamWorkflowsConfig.objects.get(team=self.team).email_sending_tier == expected_tier
+ assert not ActivityLog.objects.filter(scope="Team", activity="email_sending_tier_changed").exists()
@parameterized.expand([("promotion", 0), ("demotion", 3)])
def test_pinned_team_never_moves(self, _name: str, tier: int) -> None:
@@ -470,15 +494,21 @@ class TestBackfillEmailSendingTiers(BaseTest):
decisions = BackfillCommand()._decide(histories={}, team_ids=[self.team.id])
assert [(d.new_tier, d.reason) for d in decisions] == [(0, "staff_suspension")]
- def test_apply_does_not_overwrite_a_concurrent_staff_change(self) -> None:
+ @parameterized.expand([("unchanged_row", False, 4), ("pinned_by_staff_during_scan", True, 1)])
+ def test_apply_audits_only_the_writes_it_makes(self, _name: str, pinned: bool, expected_tier: int) -> None:
# The fleet scan computes decisions before it writes. A staff pin landing in that gap must
# win over the stale decision, matching the daily sweep's compare-and-set.
TeamWorkflowsConfig.objects.update_or_create(
- team=self.team, defaults={"email_sending_tier": 1, "email_sending_tier_pinned": True}
+ team=self.team, defaults={"email_sending_tier": 1, "email_sending_tier_pinned": pinned}
+ )
+ decision = TierDecision(team_id=self.team.id, previous_tier=1, new_tier=4, reason="clean_and_used")
+ assert BackfillCommand()._apply([decision]) == (0 if pinned else 1)
+ assert TeamWorkflowsConfig.objects.get(team=self.team).email_sending_tier == expected_tier
+
+ entries = ActivityLog.objects.filter(scope="Team", team_id=self.team.id, activity="email_sending_tier_changed")
+ assert [(entry.detail or {})["trigger"]["job_type"] for entry in entries] == (
+ [] if pinned else ["backfill_workflows_email_sending_tiers"]
)
- stale = TierDecision(team_id=self.team.id, previous_tier=1, new_tier=4, reason="clean_and_used")
- assert BackfillCommand()._apply([stale]) == 0
- assert TeamWorkflowsConfig.objects.get(team=self.team).email_sending_tier == 1
def test_history_for_a_deleted_team_is_dropped(self) -> None:
# app_metrics2 in ClickHouse outlives a team deleted from Postgres, so its history can name a