Add docs on registering client events

Author: kiendang

docs/source/operators/telemetry.rst

@@ -11,7 +11,7 @@ The Notebook Server can be configured to record structured events from a running
 .. warning::
     Do NOT rely on this feature for security or auditing purposes. Neither `server <#emitting-server-events>`_ nor `client <#eventlog-endpoint>`_ events are protected against meddling. For server events, those who have access to the environment can change the server code to emit whatever they want. The same goes for client events where nothing prevents users from sending spurious data to the `eventlog` endpoint.
 
-Emitting Server Events
+Emitting server events
 ----------------------
 
 Event logging is handled by its ``Eventlog`` object. This leverages Python's standing logging_ library to emit, filter, and collect event data.
@@ -37,8 +37,16 @@ Here's a basic example for emitting events from the `contents` service:
 
 The output is a file, ``"event.log"``, with events recorded as JSON data.
 
-`eventlog` endpoint
--------------------
+Server event schemas
+--------------------
+
+.. toctree::
+   :maxdepth: 2
+
+   events/index
+
+The ``eventlog`` endpoint
+-------------------------
 
 The Notebook Server provides a public REST endpoint for external applications to validate and log events
 through the Server's Event Log.
@@ -54,11 +62,37 @@ Events that are validated by this endpoint must have their schema listed in the
 
 .. _below:
 
+Register client event schemas
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Server Event schemas
---------------------
+``jupyter_server`` looks for locations of schema files provided by external packages by looking into the ``jupyter_telemetry`` entry point and then loads the files using the ``importlib.resources`` standard library.
 
-.. toctree::
-   :maxdepth: 2
+For example, suppose there is a ``client_events`` package which wants to send events with schemas ``schema1.yaml``, ``schema2.yaml`` and ``extra_schema.yaml`` to the ``eventlog`` endpoint and has the following package structure:
 
-   events/index
+.. code-block:: text
+
+    client_events/
+        __init__.py
+        schemas/
+            __init__.py
+            schema1.yaml
+            schema2.yaml
+        extras/
+            __init__.py
+            extra_schema.yaml
+
+``schema1.yaml`` and ``schema2.yaml`` are resources under ``client_events.schemas`` and ``extra_schema.yaml`` under ``client_events.extras``. To make these schemas discoverable by ``jupyter_server``, create an entry point under the ``jupyter_telemetry`` group which resolves to a list containing their locations, in this case ``['client_events.schemas', 'client_events.extras']``:
+
+In :file:`setup.cfg`
+
+.. code-block:: yaml
+
+    [options.entry_points]
+    jupyter_telemetry =
+        my-event-entry-point = client_events:JUPYTER_TELEMETRY_SCHEMAS
+
+In :file:`client_events/__init__.py`
+
+.. code-block:: python
+
+    JUPYTER_TELEMETRY_SCHEMAS = ['client_events.schemas', 'client_events.extras']