[Telemetry] Add basic telemetry to Jupyter server and begin emitting server events

.gitignore

@@ -1,11 +1,13 @@
 MANIFEST
+docs/source/operators/events
 build
 dist
 _build
 docs/man/*.gz
 docs/source/api/generated
 docs/source/config.rst
 docs/gh-pages
+docs/source/events
 jupyter_server/i18n/*/LC_MESSAGES/*.mo
 jupyter_server/i18n/*/LC_MESSAGES/nbjs.json
 jupyter_server/static/style/*.min.css*
@@ -36,4 +38,3 @@ config.rst
 
 # copied changelog file
 docs/source/other/changelog.md
-

MANIFEST.in

@@ -9,6 +9,9 @@ include package.json
 # include everything in package_data
 recursive-include jupyter_server *
 
+# Event Schemas
+graft jupyter_server/event_schemas
+
 # Documentation
 graft docs
 exclude docs/\#*

docs/doc-requirements.txt

@@ -10,3 +10,6 @@ sphinxcontrib-openapi
 sphinxemoji
 myst-parser
 pydata_sphinx_theme
+git+https://github.com/pandas-dev/pydata-sphinx-theme.git@master
+sphinx-jsonschema
+jupyter_telemetry_sphinxext

docs/source/_static/theme_overrides.css

@@ -0,0 +1,13 @@
+/* override table width restrictions */
+@media screen and (min-width: 767px) {
+
+   .wy-table-responsive table td {
+      /* !important prevents the common CSS stylesheets from overriding
+         this as on RTD they are loaded after this stylesheet */
+      white-space: normal !important;
+   }
+
+   .wy-table-responsive {
+      overflow: visible !important;
+   }
+}

docs/source/conf.py

@@ -77,7 +77,9 @@
     'IPython.sphinxext.ipython_console_highlighting',
     'sphinxcontrib_github_alt',
     'sphinxcontrib.openapi',
-    'sphinxemoji.sphinxemoji'
+    'sphinxemoji.sphinxemoji',
+    'sphinx-jsonschema',
+    'jupyter_telemetry_sphinxext'
 ]
 
 myst_enable_extensions = ["html_image"]
@@ -216,6 +218,12 @@
 #       since it is needed to properly generate _static in the build directory
 html_static_path = ['_static']
 
+html_context = {
+    'css_files': [
+            '_static/theme_overrides.css',  # override wide tables in RTD theme
+        ],
+}
+
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied
 # directly to the root of the documentation.
@@ -380,6 +388,11 @@
 # import before any doc is built, so _ is guaranteed to be injected
 import jupyter_server.transutils
 
+# Jupyter telemetry configuration values.
+jupyter_telemetry_schema_source = osp.join(HERE, '../../jupyter_server/event_schemas')
+jupyter_telemetry_schema_output = osp.join(HERE, 'operators/events')
+# Title of the index page that lists all found schemas
+jupyter_telemetry_index_title = 'Telemetry Event Schemas'
 
 def setup(app):
     dest = osp.join(HERE, 'other', 'changelog.md')

docs/source/operators/index.rst

@@ -12,4 +12,5 @@ These pages are targeted at people using, configuring, and/or deploying multiple
    configuring-extensions
    migrate-from-nbserver
    public-server
-   security
+   security
+   telemetry

docs/source/operators/telemetry.rst

@@ -0,0 +1,63 @@
+Eventlogging and Telemetry
+==========================
+
+Jupyter Server can be configured to record structured events from a running server using Jupyter's `Telemetry System`_. The types of events that Jupyter Server emits are defined by `JSON schemas`_ listed below_ emitted as JSON data, defined and validated by the JSON schemas listed below.
+
+
+.. _logging: https://docs.python.org/3/library/logging.html
+.. _`Telemetry System`: https://github.com/jupyter/telemetry
+.. _`JSON schemas`: https://json-schema.org/
+
+.. 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
+----------------------
+
+Event logging is handled by its ``Eventlog`` object. This leverages Python's standing logging_ library to emit, filter, and collect event data.
+
+To begin recording events, you'll need to set two configurations:
+
+    1. ``handlers``: tells the EventLog *where* to route your events. This trait is a list of Python logging handlers that route events to
+    2. ``allows_schemas``: tells the EventLog *which* events should be recorded. No events are emitted by default; all recorded events must be listed here.
+
+Here's a basic example for emitting events from the `contents` service:
+
+.. code-block::
+
+    import logging
+
+    c.EventLog.handlers = [
+        logging.FileHandler('event.log'),
+    ]
+
+    c.EventLog.allowed_schemas = [
+        'hub.jupyter.org/server-action'
+    ]
+
+The output is a file, ``"event.log"``, with events recorded as JSON data.
+
+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.
+
+To log events, send a `POST` request to the `/api/eventlog` endpoint. The body of the request should be a
+JSON blog and is required to have the follow keys:
+
+    1. `'schema'` : the event's schema ID.
+    2. `'version'` : the version of the event's schema.
+    3. `'event'` : the event data in JSON format.
+
+Events that are validated by this endpoint must have their schema listed in the `allowed_schemas` trait listed above.
+
+.. _below: