feat: add mixpanel telemetry for session duration

Author: maartenbreddels

.pre-commit-config.yaml

@@ -26,5 +26,5 @@ repos:
     hooks:
       - id: mypy
         args: [--no-strict-optional, --ignore-missing-imports]
-        additional_dependencies: [types-requests, types-markdown, types-PyYAML]
+        additional_dependencies: [types-requests, types-markdown, types-PyYAML, types-filelock]
         exclude: tests/unit/solara_test_apps/multipage/04-a_directory/*

pyproject.toml

@@ -17,6 +17,7 @@ dependencies = [
     "reacton>=0.16.0",
     "ipywidgets<8",
     "diskcache",
+    "filelock",
     "markdown",
     "pygments",
     "pymdown-extensions",
@@ -67,6 +68,7 @@ dev = [
     "types-markdown",
     "types-PyYAML",
     "pytest",
+    "pytest-mock",
     "pytest-cov",
     "pytest-timeout",
     "pre-commit",

solara/server/settings.py

@@ -1,6 +1,25 @@
+import os
+import uuid
 from enum import Enum
+from pathlib import Path
 
 import pydantic
+from filelock import FileLock
+
+
+def get_solara_home() -> Path:
+    """Get solara home directory, defaults to $HOME/.solara.
+
+    The $SOLARA_HOME environment variable can be set to override this default.
+
+    If both $SOLARA_HOME and $HOME are not define, the current working directory is used.
+    """
+    if "SOLARA_HOME" in os.environ:
+        return Path(os.environ["SOLARA_HOME"])
+    elif "HOME" in os.environ:
+        return Path(os.path.join(os.environ["HOME"], ".solara"))
+    else:
+        return Path(os.getcwd())
 
 
 class ThemeVariant(str, Enum):
@@ -20,6 +39,19 @@ class Config:
         env_file = ".env"
 
 
+class Telemetry(pydantic.BaseSettings):
+    mixpanel_token: str = "91845eb13a68e3db4e58d64ad23673b7"
+    mixpanel_enable: bool = True
+    server_user_id: str = "not_set"
+    server_fingerprint: str = str(uuid.getnode())
+    server_session_id: str = str(uuid.uuid4())
+
+    class Config:
+        env_prefix = "solara_telemetry_"
+        case_sensitive = False
+        env_file = ".env"
+
+
 class MainSettings(pydantic.BaseSettings):
     use_pdb: bool = False
     mode: str = "production"
@@ -34,3 +66,16 @@ class Config:
 
 main = MainSettings()
 theme = ThemeSettings()
+telemetry = Telemetry()
+
+
+home = get_solara_home()
+if not home.exists():
+    home.mkdir(parents=True, exist_ok=True)
+
+if telemetry.server_user_id == "not_set":
+    server_user_id_file = home / "server_user_id.txt"
+    with FileLock(str(server_user_id_file) + ".lock"):
+        if not server_user_id_file.exists():
+            server_user_id_file.write_text(str(uuid.uuid4()))
+        telemetry.server_user_id = server_user_id_file.read_text()

solara/server/starlette.py

@@ -17,7 +17,7 @@
 from solara.server import reload
 
 from . import app as appmod
-from . import patch, server, websocket
+from . import patch, server, telemetry, websocket
 from .cdn_helper import cdn_url_path, default_cache_dir, get_path
 
 os.environ["SERVER_SOFTWARE"] = "solara/" + str(solara.__version__)
@@ -192,6 +192,11 @@ def on_startup():
     # TODO: configure and set max number of threads
     # see https://github.com/encode/starlette/issues/1724
     reload.reloader.start()
+    telemetry.server_start()
+
+
+def on_shutdown():
+    telemetry.server_stop()
 
 
 routes = [
@@ -211,5 +216,6 @@ def on_startup():
 app = Starlette(
     routes=routes,
     on_startup=[on_startup],
+    on_shutdown=[on_shutdown],
 )
 patch.patch()

solara/server/telemetry.py

@@ -0,0 +1,80 @@
+import json
+import logging
+import time
+import uuid
+from typing import Dict, Optional
+from urllib.parse import quote
+
+import ipyvue
+import ipyvuetify
+import ipywidgets
+import requests
+
+import solara
+
+from . import settings
+
+logger = logging.getLogger("solara.server.telemetry")
+
+_server_user_id_override = None
+_server_start_time = time.time()
+
+
+solara_props = {
+    "solara_version": solara.__version__,
+    "ipywidgets_version": ipywidgets.__version__,
+    "ipyvuetify_version": ipyvuetify.__version__,
+    "ipyvue_version": ipyvue.__version__,
+}
+
+
+def override_server_user_id(server_user_id: str):
+    global _server_user_id_override
+    _server_user_id_override = server_user_id
+
+
+def get_server_user_id():
+    return _server_user_id_override or settings.telemetry.server_user_id
+
+
+def track(event: str, props: Optional[Dict] = None):
+    if not settings.telemetry.mixpanel_enable:
+        return
+    event_item = {
+        "event": event,
+        "properties": {
+            "token": settings.telemetry.mixpanel_token,
+            "fingerprint": settings.telemetry.server_fingerprint,
+            "time": int(time.time() * 1000),
+            "distinct_id": get_server_user_id(),
+            # can be useful to get of session duration
+            "session_id": settings.telemetry.server_session_id,
+            "$insert_id": str(uuid.uuid4()),  # to de-duplicate events
+            **(solara_props or {}),
+            **(props or {}),
+        },
+    }
+    try:
+        requests.post(
+            "https://api.mixpanel.com/track/",
+            headers={"content-type": "application/x-www-form-urlencoded"},
+            data=f"data={quote(json.dumps([event_item]))}",
+            timeout=1,
+        )
+    except Exception:
+        logger.exception("Failed mixpanel API call")
+
+
+def server_start():
+    global _server_start_time
+    _server_start_time = time.time()
+    track("Solara server start")
+
+
+def server_stop():
+    duration = time.time() - _server_start_time
+    track("Solara server stop", {"duration_seconds": duration})
+
+
+if __name__ == "__main__":
+    track("Solara test event", {"where": "command line"})

solara/website/pages/docs/content/20-understanding/50-solara-server.md

@@ -1,26 +1,11 @@
-# Scopes
+# Solara server
 
-## Application scope
+The solara server enables running ipywidgets based applications without a real Jupyter kernel, allowing multiple "Virtual kernels" to share the same process for better performance and scalability.
 
-Does not exist (yet), although equals process scope when using a single worker. Could be implemented using Redis.
 
-## Worker scope
+## Telemetry
 
-The scope of a single worker. E.g. all Python imported modules live in this scope, so Solara does not explicitly support this. Your application (when using React elements) will also live in this scope.
+Solara uses Mixpanel to collect usage of the solara server. We track when a server is started and stopped. To opt out of mixpanel telemetry, either:
 
-```python
-import solara as sol
-# only load a global dataframe once per worker
-if "df" not in solara.scope.worker:
-    process_scope["df"] = ....
-```
-
-## User scope
-
-Things like shopping carts should go here.
-
-## UI scope
-
-Connected to the life-time of a single browser tab.
-
-## React scope
+ * Set the environmental variable `SOLARA_TELEMETRY_MIXPANEL_ENABLE` to `False`.
+ * Install [python-dotenv](https://pypi.org/project/python-dotenv/) and put `SOLARA_TELEMETRY_MIXPANEL_ENABLE=False` in a `.env` file.

tests/conftest.py

@@ -3,9 +3,12 @@
 
 import pytest
 
+import solara.server.settings
 from solara.server import kernel, patch
 from solara.server.app import AppContext
 
+solara.server.settings.telemetry.mixpanel_token = "adbf863d17cba80db608788e7fce9843"
+
 
 @pytest.fixture(scope="session")
 def solara_patched():

tests/unit/telemetry_tests.py

@@ -0,0 +1,26 @@
+import json
+import unittest.mock
+from urllib.parse import unquote
+
+import requests
+
+import solara.server.telemetry
+
+
+def test_telemetry_basic(mocker):
+
+    post: unittest.mock.MagicMock = mocker.spy(requests, "post")
+    solara.server.telemetry.track("test_event", {"test_prop": "test_value"})
+    post.assert_called_once()
+    data = json.loads(unquote(post.call_args[1]["data"])[5:])[0]  # type: ignore
+    assert data["event"] == "test_event"
+
+
+def test_telemetry_server_start_stopc(mocker):
+    post: unittest.mock.MagicMock = mocker.spy(requests, "post")
+    solara.server.telemetry.server_start()
+    solara.server.telemetry.server_stop()
+    post.assert_called()
+    data = json.loads(unquote(post.call_args[1]["data"])[5:])[0]  # type: ignore
+    assert data["event"] == "Solara server stop"
+    assert data["properties"]["duration_seconds"] > 0