How chili-epfl/jupyter-analytics-telemetry works
Project type and purpose
• This is a hybrid JupyterLab extension combining a TypeScript‐based frontend plugin and a Python‐based server extension.
• Its purpose is to capture user interaction events in JupyterLab (e.g., cell execution, focus changes, notebook alterations) and forward them to a remote analytics backend.
File structure
• Top-level language divisions:
• Python server extension:
– setup.py, pyproject.toml, jupyterlab_unianalytics_telemetry/handlers.py (HTTP handlers), schema/ (JSON schemas for endpoints and settings)
– tests via pytest (conftest.py, jupyterlab_unianalytics_telemetry/tests)
• TypeScript frontend extension:
– src/ (PanelManager.ts, dataCollectionPlugin.ts, handler.ts, api.ts, trackers/, websocket/)
– tsconfig.json, babel.config.js, jest.config.js (build and test configurations)
• CI/DevOps:
– .github/workflows, binder/, ui-tests/ (Playwright/Galata integration tests)
• Architectural patterns: JupyterLab plugin API for frontend; event‐driven “disposable” trackers; a server‐side HTTP API; WebSocket support for chat or streaming; schema‐driven validation of payloads.
README for additional insights
• Confirms the dual (frontend + server) extension model.
• Lists dependencies (JupyterLab ≥3.1.0, Node.js, Python, yarn/jlpm).
• Describes testing: Jest for frontend, pytest for server, Playwright/Galata for integration.
a. Main components:
– JupyterLab Notebook UI (host application)
– Frontend Telemetry Plugin
• Trackers (AlterationDisposable, ExecutionDisposable, FocusDisposable, etc.)
• DataCollectionPlugin orchestrator
• API module & WebsocketManager
– Jupyter Server Extension
• HTTP/WebSocket handlers (handlers.py)
• JSON schemas (schema/*.json) for request validation
– Remote Analytics Backend (external service)
– CI/CD and Testing (GitHub Actions, Binder, Playwright)
b. Relationships & interactions:
1. User interacts with Notebook UI → Frontend Trackers emit events
2. DataCollectionPlugin batches/forms events → handler.ts
3. handler.ts calls api.ts (HTTP POST to server extension endpoints) or WebsocketManager (long‐lived channel)
4. Server extension handlers validate against schema and forward payload to Remote Analytics Backend
5. CI/CD pipelines validate build, tests, integration tests
c. Architectural patterns & principles:
– Plugin modularity: clear separation of trackers, data collection, transport
– Event‐driven flow with disposables to manage lifecycle
– Schema‐driven validation for robustness
– Dual‐language split: frontend vs. server responsibility
d. Key technologies:
– TypeScript, JupyterLab Plugin API, WebSocket, Jest
– Python, Jupyter Server Extension API, FastAPI‐style handlers (pytest testing)
– JSON Schema, Playwright/Galata for UI tests, GitHub Actions for CI