Open source video conferencing app powered by LiveKit. Built with Django and React.
✨(backend) introduce a configurable analytics system
lebaudantoine9ba97fd14f59
diff --git a/src/backend/core/analytics/__init__.py b/src/backend/core/analytics/__init__.pynew file mode 100644index 00000000..d5d4148c--- /dev/null+++ b/src/backend/core/analytics/__init__.py@@ -0,0 +1,59 @@+"""+Pluggable analytics.++Usage anywhere in the codebase:++ from core import analytics++ analytics.capture(request.user, "room_created", {"room_id": str(room.pk)})++The concrete backend is resolved lazily from Django settings, so swapping+PostHog for anything else is a configuration change, not a code change.+"""++from functools import lru_cache+from typing import Any++from django.conf import settings+from django.utils.module_loading import import_string++from .base import AnalyticsBackend, NoOpAnalytics+from .events import AnalyticsEvent++__all__ = [+ "get_analytics",+ "identify",+ "capture",+ "AnalyticsBackend",+ "AnalyticsEvent",+]+++@lru_cache(maxsize=1)+def get_analytics() -> AnalyticsBackend:+ """Instantiate the configured backend once per process."""+ dotted_path = getattr(settings, "ANALYTICS_BACKEND", None)+ options = getattr(settings, "ANALYTICS_BACKEND_SETTINGS", {}) or {}++ if not dotted_path:+ return NoOpAnalytics()++ backend_class = import_string(dotted_path)+ return backend_class(**options)+++# Convenience module-level shortcuts++analytics_instance = get_analytics()+++def identify(user, properties: dict[str, Any] | None = None) -> None:+ """Associate traits with an identified user."""+ analytics_instance.identify(user, properties)+++def capture(+ user, event: AnalyticsEvent, properties: dict[str, Any] | None = None+) -> None:+ """Record an event performed by an identified user."""+ analytics_instance.capture(user, event, properties)diff --git a/src/backend/core/analytics/base.py b/src/backend/core/analytics/base.pynew file mode 100644index 00000000..3c2b6b69--- /dev/null+++ b/src/backend/core/analytics/base.py@@ -0,0 +1,50 @@+"""Analytics backend protocol and default no-op implementation."""++from typing import Any, Protocol++from ..models import User+from .events import AnalyticsEvent+++class AnalyticsBackend(Protocol):+ """+ Interface every analytics backend must implement.++ Backends are instantiated once (singleton) with the kwargs declared in+ settings.ANALYTICS_BACKEND_SETTINGS, e.g.:++ ANALYTICS_BACKEND = "core.analytics.posthog.PostHogAnalytics"+ ANALYTICS_BACKEND_SETTINGS = {"api_key": "...", "host": "..."}+ """++ def __init__(self, **kwargs: Any) -> None: ...++ def identify(self, user: User, properties: dict[str, Any] | None = None) -> None:+ """Associate traits (email, name, ...) with an identified user."""++ def capture(+ self,+ user: User,+ event: AnalyticsEvent,+ properties: dict[str, Any] | None = None,+ ) -> None:+ """Record an event performed by an identified user."""++ def shutdown(self) -> None:+ """Flush pending events. Called on process exit."""+++class NoOpAnalytics:+ """Default backend: silently discards everything."""++ def __init__(self, **kwargs: Any) -> None:+ """No-op: accepts and ignores any backend settings kwargs."""++ def identify(self, user: User, properties=None) -> None:+ """No-op: discards identify calls."""++ def capture(self, user, event, properties=None) -> None:+ """No-op: discards captured events."""++ def shutdown(self) -> None:+ """No-op: nothing to flush."""diff --git a/src/backend/core/analytics/events.py b/src/backend/core/analytics/events.pynew file mode 100644index 00000000..d8f3e7ec--- /dev/null+++ b/src/backend/core/analytics/events.py@@ -0,0 +1,10 @@+"""Catalog of all analytics events emitted by the backend."""++from enum import StrEnum+++class AnalyticsEvent(StrEnum):+ """All trackable events. Values are the wire names sent to the provider."""++ # Rooms+ ROOM_CREATED = "room_created"diff --git a/src/backend/core/analytics/posthog.py b/src/backend/core/analytics/posthog.pynew file mode 100644index 00000000..1fef96b9--- /dev/null+++ b/src/backend/core/analytics/posthog.py@@ -0,0 +1,74 @@+"""PostHog implementation of the analytics backend protocol."""++import logging+from typing import Any++from posthog import Posthog++from ..models import User+from .events import AnalyticsEvent++logger = logging.getLogger(__name__)+++class PostHogAnalytics:+ """Send events to PostHog, keyed on the user's primary key (UUID)."""++ def __init__(+ self,+ *,+ api_key: str,+ host: str = "https://eu.i.posthog.com",+ **kwargs: Any,+ ) -> None:++ # The SDK batches and sends in a background thread by default,+ # so calls below never block the request/response cycle.+ self._client = Posthog(+ project_api_key=api_key,+ host=host,+ **kwargs,+ )++ @staticmethod+ def _distinct_id(user: User) -> str | None:+ """Return the PostHog distinct_id for a user, or None if anonymous."""+ if user is None or not getattr(user, "is_authenticated", False):+ return None+ return str(user.pk)++ def identify(self, user: User, properties: dict[str, Any] | None = None) -> None:+ """Associate traits (email, name, ...) with an identified user."""+ distinct_id = self._distinct_id(user)+ if distinct_id is None:+ return+ try:+ self._client.set(+ distinct_id=distinct_id,+ properties=properties or {},+ )+ except Exception: # pylint: disable=broad-exception-caught+ logger.exception("PostHog identify failed")++ def capture(+ self,+ user: User,+ event: AnalyticsEvent,+ properties: dict[str, Any] | None = None,+ ) -> None:+ """Record an event performed by an identified user."""+ distinct_id = self._distinct_id(user)+ if distinct_id is None:+ return+ try:+ self._client.capture(+ distinct_id=distinct_id,+ event=str(event),+ properties=properties or {},+ )+ except Exception: # pylint: disable=broad-exception-caught+ logger.exception("PostHog capture failed for event %s", event)++ def shutdown(self) -> None:+ """Flush pending events. Called on process exit."""+ self._client.shutdown()diff --git a/src/backend/core/tests/analytics/__init__.py b/src/backend/core/tests/analytics/__init__.pynew file mode 100644index 00000000..e69de29bdiff --git a/src/backend/core/tests/analytics/test_posthog.py b/src/backend/core/tests/analytics/test_posthog.pynew file mode 100644index 00000000..87bb19ef--- /dev/null+++ b/src/backend/core/tests/analytics/test_posthog.py@@ -0,0 +1,263 @@+"""+Unit tests for PostHogAnalytics.+"""++# pylint: disable=redefined-outer-name,unused-argument,protected-access++from unittest.mock import patch++from django.contrib.auth.models import AnonymousUser++import pytest++from core.analytics.events import AnalyticsEvent+from core.analytics.posthog import PostHogAnalytics+from core.factories import UserFactory++pytestmark = pytest.mark.django_db+++# ==============================+# __init__+# ==============================+++@patch("core.analytics.posthog.Posthog")+def test_init_constructs_posthog_client_with_api_key_and_host(mock_posthog_cls):+ """Should forward api_key and host to the Posthog SDK constructor."""+ PostHogAnalytics(api_key="my-key", host="https://custom.i.posthog.com")++ mock_posthog_cls.assert_called_once_with(+ project_api_key="my-key",+ host="https://custom.i.posthog.com",+ )+++@patch("core.analytics.posthog.Posthog")+def test_init_defaults_to_eu_host(mock_posthog_cls):+ """Should default host to the EU PostHog cloud when not specified."""+ PostHogAnalytics(api_key="my-key")++ _, kwargs = mock_posthog_cls.call_args+ assert kwargs["host"] == "https://eu.i.posthog.com"+++@patch("core.analytics.posthog.Posthog")+def test_init_forwards_extra_kwargs_to_client(mock_posthog_cls):+ """Should pass through arbitrary extra kwargs (e.g. debug, disabled) to the SDK."""+ PostHogAnalytics(api_key="my-key", debug=True, disabled=False)++ _, kwargs = mock_posthog_cls.call_args+ assert kwargs["debug"] is True+ assert kwargs["disabled"] is False+++# ==============================+# _distinct_id+# ==============================+++@patch("core.analytics.posthog.Posthog")+def test_distinct_id_returns_none_for_none_user(mock_posthog_cls):+ """Should return None when user is None."""+ backend = PostHogAnalytics(api_key="test-api-key")++ assert backend._distinct_id(None) is None+++@patch("core.analytics.posthog.Posthog")+def test_distinct_id_returns_none_for_anonymous_user(mock_posthog_cls):+ """Should return None when user.is_authenticated is falsy."""+ backend = PostHogAnalytics(api_key="test-api-key")++ assert backend._distinct_id(AnonymousUser()) is None+++@patch("core.analytics.posthog.Posthog")+def test_distinct_id_returns_none_when_attribute_missing(mock_posthog_cls):+ """Should return None when the user object has no is_authenticated attribute at all."""+ backend = PostHogAnalytics(api_key="test-api-key")++ assert backend._distinct_id(object()) is None+++@patch("core.analytics.posthog.Posthog")+def test_distinct_id_returns_stringified_pk_for_authenticated_user(mock_posthog_cls):+ """Should return str(user.pk) for an authenticated user."""+ backend = PostHogAnalytics(api_key="test-api-key")+ user = UserFactory()++ assert backend._distinct_id(user) == str(user.pk)+++# ==============================+# identify+# ==============================+++@patch("core.analytics.posthog.Posthog")+def test_identify_noop_for_anonymous_user(mock_posthog_cls):+ """Should not call the SDK when the user is anonymous."""+ backend = PostHogAnalytics(api_key="test-api-key")++ backend.identify(AnonymousUser(), {"email": "[email protected]"})++ mock_posthog_cls.return_value.set.assert_not_called()+++@patch("core.analytics.posthog.Posthog")+def test_identify_noop_for_none_user(mock_posthog_cls):+ """Should not call the SDK when user is None."""+ backend = PostHogAnalytics(api_key="test-api-key")++ backend.identify(None, {"email": "[email protected]"})++ mock_posthog_cls.return_value.set.assert_not_called()+++@patch("core.analytics.posthog.Posthog")+def test_identify_sends_set_properties_for_authenticated_user(mock_posthog_cls):+ """Should call capture with event=$identify and properties wrapped in $set."""+ backend = PostHogAnalytics(api_key="test-api-key")+ user = UserFactory()++ backend.identify(user, {"email": "[email protected]", "name": "A"})++ mock_posthog_cls.return_value.set.assert_called_once_with(+ distinct_id=str(user.pk),+ properties={"email": "[email protected]", "name": "A"},+ )+++@patch("core.analytics.posthog.Posthog")+def test_identify_defaults_properties_to_empty_dict(mock_posthog_cls):+ """Should send an empty $set payload when properties is None."""+ backend = PostHogAnalytics(api_key="test-api-key")+ user = UserFactory()++ backend.identify(user, None)++ mock_posthog_cls.return_value.set.assert_called_once_with(+ distinct_id=str(user.pk),+ properties={},+ )+++@patch("core.analytics.posthog.Posthog")+def test_identify_swallows_sdk_exceptions(mock_posthog_cls):+ """Should log and not raise when the SDK call fails."""+ mock_posthog_cls.return_value.set.side_effect = RuntimeError("network down")+ backend = PostHogAnalytics(api_key="test-api-key")+ user = UserFactory()++ # Must not propagate.+ backend.identify(user, {"email": "[email protected]"})+++# ==============================+# capture+# ==============================+++@patch("core.analytics.posthog.Posthog")+def test_capture_noop_for_anonymous_user(mock_posthog_cls):+ """Should not call the SDK when the user is anonymous."""+ backend = PostHogAnalytics(api_key="test-api-key")++ backend.capture(AnonymousUser(), AnalyticsEvent.ROOM_CREATED, {"room_id": "1"})++ mock_posthog_cls.return_value.capture.assert_not_called()+++@patch("core.analytics.posthog.Posthog")+def test_capture_noop_for_none_user(mock_posthog_cls):+ """Should not call the SDK when user is None."""+ backend = PostHogAnalytics(api_key="test-api-key")++ backend.capture(None, AnalyticsEvent.ROOM_CREATED, {"room_id": "1"})++ mock_posthog_cls.return_value.capture.assert_not_called()+++@patch("core.analytics.posthog.Posthog")+def test_capture_sends_event_and_properties_for_authenticated_user(mock_posthog_cls):+ """Should call capture with the distinct_id, event name, and properties."""+ backend = PostHogAnalytics(api_key="test-api-key")+ user = UserFactory()++ backend.capture(user, AnalyticsEvent.ROOM_CREATED, {"room_id": "room-1"})++ mock_posthog_cls.return_value.capture.assert_called_once_with(+ distinct_id=str(user.pk),+ event="room_created",+ properties={"room_id": "room-1"},+ )+++@patch("core.analytics.posthog.Posthog")+def test_capture_serializes_event_enum_to_plain_string(mock_posthog_cls):+ """Should send the wire string, not the AnalyticsEvent enum member, to the SDK."""+ backend = PostHogAnalytics(api_key="test-api-key")+ user = UserFactory()++ backend.capture(user, AnalyticsEvent.ROOM_CREATED)++ _, kwargs = mock_posthog_cls.return_value.capture.call_args+ assert kwargs["event"] == "room_created"+ assert isinstance(+ kwargs["event"], str+ ) # not AnalyticsEvent, not StrEnum subclass leaking through+++@patch("core.analytics.posthog.Posthog")+def test_capture_defaults_properties_to_empty_dict(mock_posthog_cls):+ """Should send an empty properties dict when properties is None."""+ backend = PostHogAnalytics(api_key="test-api-key")+ user = UserFactory()++ backend.capture(user, AnalyticsEvent.ROOM_CREATED, None)++ mock_posthog_cls.return_value.capture.assert_called_once_with(+ distinct_id=str(user.pk),+ event="room_created",+ properties={},+ )+++@patch("core.analytics.posthog.Posthog")+def test_capture_swallows_sdk_exceptions(mock_posthog_cls):+ """Should log and not raise when the SDK call fails."""+ mock_posthog_cls.return_value.capture.side_effect = RuntimeError("network down")+ backend = PostHogAnalytics(api_key="test-api-key")+ user = UserFactory()++ # Must not propagate.+ backend.capture(user, AnalyticsEvent.ROOM_CREATED, {"room_id": "1"})+++@patch("core.analytics.posthog.Posthog")+def test_capture_logs_the_failing_event_name_on_exception(mock_posthog_cls, caplog):+ """Should log which event failed, to aid debugging without crashing the caller."""+ mock_posthog_cls.return_value.capture.side_effect = RuntimeError("network down")+ backend = PostHogAnalytics(api_key="test-api-key")+ user = UserFactory()++ with caplog.at_level("ERROR"):+ backend.capture(user, AnalyticsEvent.ROOM_CREATED)++ assert any("PostHog capture failed" in record.message for record in caplog.records)+++# ==============================+# shutdown+# ==============================+++@patch("core.analytics.posthog.Posthog")+def test_shutdown_flushes_the_client(mock_posthog_cls):+ """Should delegate to the SDK's shutdown to flush pending events."""+ backend = PostHogAnalytics(api_key="test-api-key")++ backend.shutdown()++ mock_posthog_cls.return_value.shutdown.assert_called_once()diff --git a/src/backend/meet/settings.py b/src/backend/meet/settings.pyindex f8988273..0de934da 100755--- a/src/backend/meet/settings.py+++ b/src/backend/meet/settings.py@@ -761,6 +761,14 @@ class Base(Configuration):None, environ_name="RECORDING_DOWNLOAD_BASE_URL", environ_prefix=None)+ # Analytics+ ANALYTICS_BACKEND = values.Value(+ None, environ_name="ANALYTICS_BACKEND", environ_prefix=None+ )+ ANALYTICS_BACKEND_SETTINGS = values.DictValue(+ {}, environ_name="ANALYTICS_BACKEND_SETTINGS", environ_prefix=None+ )+# Marketing and communication settingsSIGNUP_NEW_USER_TO_MARKETING_EMAIL = values.BooleanValue(False, # When enabled, new users are automatically added to mailing list.