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(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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
index 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_deliveries
from 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_matching
from products.customer_analytics.backend.logic.feature_request_github import process_github_issue_update
logger = 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.