Package: etc-jupyterlab-telemetry-library
ETC JupyterLab Telemetry LibraryThis extension provides a JupyterLab service, identified by theIETCJupyterLabTelemetryLibraryFactorytoken, that can be used to construct aETCJupyterLabTelemetryLibraryinstance that exposes Signals associated with user actions in the Notebook.TheIETCJupyterLabTelemetryLibraryFactoryToken represents aservicethat can be consumed by a JupyterLab plugin similar to how core services are consumed by plugins:Core Tokens. See theUsagesection for instructions on how to consume the service.The ETCJupyterLabTelemetryLibrary service contains Signals grouped according to their functionality. For example in order toconsole.logthenotebook_openevent, you would connect to the Signal like this:etcJupyterLabTelemetryLibrary.notebookOpenEvent.notebookOpened.connect(console.log);The following table provides the Signal Groups and their respective Signal(s).Signal GroupSignal(s)notebookClipboardEventnotebookClipboardCopied, notebookClipboardCut, notebookClipboardPastednotebookVisibilityEventnotebookVisible, notebookHiddennotebookCloseEventnotebookClosednotebookOpenEventnotebookOpenednotebookSaveEventnotebookSavednotebookScrollEventnotebookScrolledactiveCellChangeEventactiveCellChangedcellAddEventcellAddedcellRemoveEventcellRemovedcellExecutionEventcellExecutedcellErrorEventcellErroredA plugin that consumes this plugin can attach a handler to the Signal(s) of each Signal Group in order to log the event message.EventsEach event message (i.e., the message emitted by the Signal) contains a list of cells relevant to that event. See theRelevant Cellssection for details.Event Message SchemaEach event message will contain the name of the event, a list of cells that are relevant to the event, and a reference to the NotebookPanel that emitted the event.Each event message conforms to the following JSON schema.TO DORelevant CellsFor each event message, in addition to reference to the complete NotebookPanel, which contains the full contents of each cell, the top levelcellsproperty in the message will contain the cells relevant to the event.Signal(s)Relevant CellsnotebookClipboardCopied, notebookClipboardCut, notebookClipboardPastedThe cell list contains the ID of the active cell.notebookVisible, notebookHiddenThe cell list contains the IDs of the cells that are visible to the user.notebookClosedThe cell list contains the IDs of all the cells in the notebook.notebookOpenedThe cell list contains the IDs of all the cells in the notebook.notebookSavedThe cell list contains active or selected cell.notebookScrolledThe cell list contains the IDs of the cells that are visible to the user.activeCellChangedThe cell list contains the ID of the active cell.cellAddedThe cell list contains the IDs of the added cells.cellRemovedThe cell list contains the IDs of the removed cells.cellExecutedThe cell list contains the ID of the executed cell.cellErroredThe cell list contains the ID of the cell that produced the error.UsageInstall the extension according to the installation instructions.Once the extension is installed a plugin can consume the service by including it in itsrequireslist. See the below code for an example.The extension provides a service identified by theIETCJupyterLabTelemetryLibraryFactorytoken. In the following example, theconsumerplugin consumes the Token provided by theetc_jupyterlab_telemetry_libraryextension. TheETCJupyterLabTelemetryLibraryFactoryis used in order to instantiate aETCJupyterLabTelemetryLibraryfor each NotebookPanel. EachETCJupyterLabTelemetryLibraryinstance contains grouped Signals that are connected to theconsole.logmethod, which will log the events to the console.The Signals can be connected to any handler that you choose. The content of the messages can be filtered according to your needs.constplugin:JupyterFrontEndPlugin<void>={id:PLUGIN_ID,autoStart:true,requires:[INotebookTracker,IETCJupyterLabTelemetryLibraryFactory],activate:(app:JupyterFrontEnd,notebookTracker:INotebookTracker,etcJupyterLabTelemetryLibraryFactory:IETCJupyterLabTelemetryLibraryFactory)=>{(async()=>{constVERSION=(awaitrequestAPI)<string>'version';console.log(`${PLUGIN_ID},${VERSION}`);awaitapp.started;try{notebookTracker.widgetAdded.connect((sender:INotebookTracker,notebookPanel:NotebookPanel)=>{//  Handlers must be attached immediately in order to detect early events, hence we do not want to await the appearance of the Notebook.letetcJupyterLabTelemetryLibrary=etcJupyterLabTelemetryLibraryFactory.create({notebookPanel});etcJupyterLabTelemetryLibrary.notebookClipboardEvent.notebookClipboardCopied.connect(console.log);etcJupyterLabTelemetryLibrary.notebookClipboardEvent.notebookClipboardCut.connect(console.log);etcJupyterLabTelemetryLibrary.notebookClipboardEvent.notebookClipboardPasted.connect(console.log);etcJupyterLabTelemetryLibrary.notebookVisibilityEvent.notebookVisible.connect(console.log);etcJupyterLabTelemetryLibrary.notebookVisibilityEvent.notebookHidden.connect(console.log);etcJupyterLabTelemetryLibrary.notebookOpenEvent.notebookOpened.connect(console.log);etcJupyterLabTelemetryLibrary.notebookCloseEvent.notebookClosed.connect(console.log);etcJupyterLabTelemetryLibrary.notebookSaveEvent.notebookSaved.connect(console.log);etcJupyterLabTelemetryLibrary.notebookScrollEvent.notebookScrolled.connect(console.log);etcJupyterLabTelemetryLibrary.activeCellChangeEvent.activeCellChanged.connect(console.log);etcJupyterLabTelemetryLibrary.cellAddEvent.cellAdded.connect(console.log);etcJupyterLabTelemetryLibrary.cellRemoveEvent.cellRemoved.connect(console.log);etcJupyterLabTelemetryLibrary.cellExecutionEvent.cellExecuted.connect(console.log);etcJupyterLabTelemetryLibrary.cellErrorEvent.cellErrored.connect(console.log);});}catch(e){console.error(e);}})();}};ConfigurationThe extension requires a configuration file that specifies which Signalgroupswill emit events.The configuration file may be placed in any of the Jupyter Server configuration directories e.g.,/etc/jupyter. Executejupyter --pathsin order to get a list of valid configuration directories. The configuration file must be namedjupyter_etc_jupyterlab_telemetry_coursera_config.py.This is an example of a valid configuration file:c.ETCJupyterLabTelemetryLibraryApp.notebook_clipboard_event=Truec.ETCJupyterLabTelemetryLibraryApp.notebook_visibility_event=Truec.ETCJupyterLabTelemetryLibraryApp.notebook_save_event=Truec.ETCJupyterLabTelemetryLibraryApp.notebook_close_event=Truec.ETCJupyterLabTelemetryLibraryApp.notebook_open_event=Truec.ETCJupyterLabTelemetryLibraryApp.notebook_cell_remove_event=Truec.ETCJupyterLabTelemetryLibraryApp.notebook_cell_add_event=Truec.ETCJupyterLabTelemetryLibraryApp.notebook_cell_execution_event=Truec.ETCJupyterLabTelemetryLibraryApp.notebook_scroll_event=Truec.ETCJupyterLabTelemetryLibraryApp.notebook_active_cell_change_event=Truec.ETCJupyterLabTelemetryLibraryApp.notebook_cell_error_event=TrueAn Signal group can be enable or disabled by setting the respective property toTrueorFalse. This setting will enable or disable all of the Signals in the respective group.  The change will take effect each time JupyterLab is started.RequirementsJupyterLab >= 3.0InstallTo install the extension, execute:pipinstalletc_jupyterlab_telemetry_libraryUninstallTo remove the extension, execute:pipuninstalletc_jupyterlab_telemetry_libraryTroubleshootIf you are seeing the frontend extension, but it is not working, check
that the server extension is enabled:jupyterserverextensionlistIf the server extension is installed and enabled, but you are not seeing
the frontend extension, check the frontend extension is installed:jupyterlabextensionlistContributingDevelopment installNote: You will need NodeJS to build the extension package.Thejlpmcommand is JupyterLab's pinned version ofyarnthat is installed with JupyterLab. You may useyarnornpmin lieu ofjlpmbelow.# Clone the repo to your local environment# Change directory to the etc_jupyterlab_telemetry_library directory# Install package in development modepipinstall-e.# Link your development version of the extension with JupyterLabjupyterlabextensiondevelop.--overwrite# Server extension must be manually installed in develop modejupyterserverextensionenableetc_jupyterlab_telemetry_library# Rebuild extension Typescript source after making changesjlpmrunbuildYou can watch the source directory and run JupyterLab at the same time in different terminals to watch for changes in the extension's source and automatically rebuild the extension.# Watch the source directory in one terminal, automatically rebuilding when neededjlpmrunwatch# Run JupyterLab in another terminaljupyterlabWith the watch command running, every saved change will immediately be built locally and available in your running JupyterLab. Refresh JupyterLab to load the change in your browser (you may need to wait several seconds for the extension to be rebuilt).By default, thejlpm run buildcommand generates the source maps for this extension to make it easier to debug using the browser dev tools. To also generate source maps for the JupyterLab core extensions, you can run the following command:jupyterlabbuild--minimize=FalseDevelopment uninstall# Server extension must be manually disabled in develop modejupyterserverextensiondisableetc_jupyterlab_telemetry_library
pipuninstalletc_jupyterlab_telemetry_libraryIn development mode, you will also need to remove the symlink created byjupyter labextension developcommand. To find its location, you can runjupyter labextension listto figure out where thelabextensionsfolder is located. Then you can remove the symlink named@educational-technology-collective/etc_jupyterlab_telemetry_librarywithin that folder.Packaging the extensionSeeRELEASE