: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.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
feat(customer-analytics): capture email thread matching lifecycle events (#121182)
Arthur Moreira de Deus840c71e528bd
diff --git a/products/customer_analytics/backend/logic/email_matching_monitoring.py b/products/customer_analytics/backend/logic/email_matching_monitoring.pynew file mode 100644index 000000000000..e05f6fa80620--- /dev/null+++ b/products/customer_analytics/backend/logic/email_matching_monitoring.py@@ -0,0 +1,101 @@+"""Lifecycle events for the email thread matching Celery tasks.++Each run emits `email_thread_matching` with `status="started"` before any work, then one+terminal status. A worker that stops without unwinding, such as on SIGKILL, sends no+terminal event, so a `started` event without a terminal event marks a lost run.+Telemetry never raises into the matching and never waits longer than the flush timeout.+"""++from __future__ import annotations++import time+import functools+from collections.abc import Iterator+from contextlib import contextmanager+from typing import Any, Final, Literal++import structlog+from celery import current_task++from posthog.cloud_utils import is_cloud+from posthog.ph_client import get_client+from posthog.utils import get_instance_region++logger = structlog.get_logger(__name__)++EMAIL_THREAD_MATCHING_EVENT: Final = "email_thread_matching"+FLUSH_TIMEOUT_SECONDS: Final = 5.0++EmailThreadMatchingType = Literal["full", "threads", "account_properties"]+++@contextmanager+def track_email_thread_matching(team_id: int, matching_type: EmailThreadMatchingType) -> Iterator[None]:+ retries = current_task.request.retries or 0+ client = _get_client_or_none()+ properties: dict[str, object] = {+ "$process_person_profile": False,+ "team_id": team_id,+ "matching_type": matching_type,+ "task_id": current_task.request.id,+ "attempt": retries + 1,+ }+ # Sent before the work, so a worker that dies mid-run still leaves its `started` event.+ _send(client, team_id, {**properties, "status": "started"})+ started_at = time.monotonic()+ try:+ yield+ except Exception as error:+ status = "retrying" if retries < (current_task.max_retries or 0) else "failed"+ # The class name only: the message can carry customer email addresses.+ _send(+ client,+ team_id,+ {+ **properties,+ "status": status,+ "duration_seconds": _seconds_since(started_at),+ "error_type": type(error).__name__,+ },+ )+ raise+ _send(client, team_id, {**properties, "status": "completed", "duration_seconds": _seconds_since(started_at)})+++def _get_client() -> Any:+ # One client per worker process: a client per run registers an exit callback that+ # `shutdown()` never removes, so per-run clients would pile up for the worker's lifetime.+ client = get_client()+ if client is not None:+ # The client's region super property overrides event properties, so it must name this deployment.+ client.super_properties["region"] = get_instance_region() or "unknown"+ return client+++def _get_client_or_none() -> Any:+ if not is_cloud():+ return None+ try:+ return _get_client()+ except Exception as error:+ logger.warning("email_thread_matching_event_client_failed", error_type=type(error).__name__)+ return None+++def _seconds_since(started_at: float) -> float:+ return round(time.monotonic() - started_at, 3)+++def _send(client: Any, team_id: int, properties: dict[str, object]) -> None:+ if client is None:+ return+ try:+ client.capture(+ distinct_id=f"email_thread_matching_team_{team_id}",+ event=EMAIL_THREAD_MATCHING_EVENT,+ properties=properties,+ )+ client.flush(timeout_seconds=FLUSH_TIMEOUT_SECONDS)+ except Exception as error:+ logger.warning("email_thread_matching_event_capture_failed", error_type=type(error).__name__)diff --git a/products/customer_analytics/backend/logic/email_matching_monitoring_test.py b/products/customer_analytics/backend/logic/email_matching_monitoring_test.pynew file mode 100644index 000000000000..5091fa16179f--- /dev/null+++ b/products/customer_analytics/backend/logic/email_matching_monitoring_test.py@@ -0,0 +1,83 @@+from typing import Any++import pytest+from unittest.mock import MagicMock, patch++from parameterized import parameterized++from products.customer_analytics.backend.logic.email_matching_monitoring import (+ FLUSH_TIMEOUT_SECONDS,+ track_email_thread_matching,+)++MODULE = "products.customer_analytics.backend.logic.email_matching_monitoring"+++class _RecordingClient:+ def __init__(self, steps: list[tuple[object, ...]], *, fail: bool = False) -> None:+ self.steps = steps+ self.fail = fail+ self.properties: list[dict[str, Any]] = []++ def capture(self, *, distinct_id: str, event: str, properties: dict[str, Any]) -> None:+ if self.fail:+ raise RuntimeError("capture unavailable")+ self.steps.append(("capture", properties["status"]))+ self.properties.append(properties)++ def flush(self, *, timeout_seconds: float | None) -> None:+ self.steps.append(("flush", timeout_seconds))+++class TestTrackEmailThreadMatching:+ def _run(self, get_client: Any, *, retries: int, error: type[Exception] | None, steps: list) -> None:+ task = MagicMock(max_retries=3)+ task.request.id = "task-1"+ task.request.retries = retries+ with (+ patch(f"{MODULE}.is_cloud", return_value=True),+ patch(f"{MODULE}._get_client", get_client),+ patch(f"{MODULE}.current_task", task),+ track_email_thread_matching(42, "threads"),+ ):+ steps.append(("run",))+ if error is not None:+ raise error()++ @parameterized.expand(+ [+ ("completed", 0, None, "completed"),+ ("first_error_retries", 0, ValueError, "retrying"),+ ("last_error_fails", 3, ValueError, "failed"),+ ]+ )+ def test_flushes_started_before_work_and_records_one_outcome(+ self, _name: str, retries: int, error: type[Exception] | None, terminal_status: str+ ) -> None:+ steps: list[tuple[object, ...]] = []+ client = _RecordingClient(steps)++ if error is None:+ self._run(lambda: client, retries=retries, error=error, steps=steps)+ else:+ with pytest.raises(error):+ self._run(lambda: client, retries=retries, error=error, steps=steps)++ flush = ("flush", FLUSH_TIMEOUT_SECONDS)+ assert steps == [("capture", "started"), flush, ("run",), ("capture", terminal_status), flush]+ terminal = client.properties[-1]+ assert terminal["attempt"] == retries + 1+ assert terminal.get("error_type") == (None if error is None else error.__name__)++ @parameterized.expand([("capture_raises",), ("client_setup_raises",)])+ def test_telemetry_failure_does_not_stop_the_matching(self, failure: str) -> None:+ steps: list[tuple[object, ...]] = []++ def get_client() -> _RecordingClient:+ if failure == "client_setup_raises":+ raise RuntimeError("consumer thread could not start")+ return _RecordingClient(steps, fail=True)++ self._run(get_client, retries=0, error=None, steps=steps)++ assert steps == [("run",)]diff --git a/products/customer_analytics/backend/tasks/tasks.py b/products/customer_analytics/backend/tasks/tasks.pyindex 59274550abdc..444a817910cb 100644--- a/products/customer_analytics/backend/tasks/tasks.py+++ b/products/customer_analytics/backend/tasks/tasks.py@@ -15,6 +15,7 @@ from products.customer_analytics.backend.facade.email_matching import ()from products.customer_analytics.backend.logic.announcements import send_pending_deliveriesfrom products.customer_analytics.backend.logic.custom_property_sync import sync_custom_property_values+from products.customer_analytics.backend.logic.email_matching_monitoring import track_email_thread_matchingfrom products.customer_analytics.backend.logic.feature_request_github import process_github_issue_updatelogger = structlog.get_logger(__name__)@@ -160,8 +161,9 @@ def rematch_account_meetings(team_id: int, account_id: str) -> None:)@with_team_scope()def recalculate_email_thread_account_links(team_id: int) -> None:- recalculate_email_thread_links(team_id)- finish_email_thread_link_recalculation(team_id)+ with track_email_thread_matching(team_id, "full"):+ recalculate_email_thread_links(team_id)+ finish_email_thread_link_recalculation(team_id)@shared_task(@@ -180,12 +182,13 @@ def recalculate_email_thread_account_links_for_account_properties(previous_known_emails: list[str],previous_email_domains: list[str],) -> None:- recalculate_email_thread_links_for_account_properties(- team_id,- account_id,- previous_known_emails=previous_known_emails,- previous_email_domains=previous_email_domains,- )+ with track_email_thread_matching(team_id, "account_properties"):+ recalculate_email_thread_links_for_account_properties(+ team_id,+ account_id,+ previous_known_emails=previous_known_emails,+ previous_email_domains=previous_email_domains,+ )@shared_task(@@ -198,7 +201,8 @@ def recalculate_email_thread_account_links_for_account_properties()@with_team_scope()def recalculate_email_thread_account_links_for_threads(team_id: int, thread_ids: list[str]) -> None:- recalculate_email_thread_links(team_id, thread_ids=thread_ids, append_only=True)+ with track_email_thread_matching(team_id, "threads"):+ recalculate_email_thread_links(team_id, thread_ids=thread_ids, append_only=True)# autoretry_for is load-bearing: bare max_retries kwargs without it are silently inert.