add docs for event-logging

docs/requirements.txt

@@ -5,3 +5,4 @@ alabaster_jupyterhub
 recommonmark==0.5.0
 sphinx-copybutton
 sphinx>=1.7
+sphinx-jsonschema

docs/source/conf.py

@@ -19,6 +19,7 @@ extensions = [
     'sphinx.ext.napoleon',
     'autodoc_traits',
     'sphinx_copybutton',
+    'sphinx-jsonschema'
 ]
 
 templates_path = ['_templates']

docs/source/events/index.rst

@@ -0,0 +1,50 @@
+Eventlogging and Telemetry
+==========================
+
+JupyterHub can be configured to record structured events from a running server using Jupyter's `Telemetry System`_. The types of events that JupyterHub 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/
+
+How to emit events
+------------------
+
+Eventlogging 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:
+
+.. 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.
+
+
+
+.. _below:
+
+Event schemas
+-------------
+
+.. toctree::
+   :maxdepth: 2
+
+   server-actions.rst

docs/source/events/server-actions.rst

@@ -0,0 +1 @@
+.. jsonschema:: ../../../jupyterhub/event-schemas/server-actions/v1.yaml

docs/source/index.rst

@@ -134,6 +134,14 @@ helps keep our community welcoming to as many people as possible.
    contributing/roadmap
    contributing/security
 
+Eventlogging and Telemetry
+--------------------------
+
+.. toctree::
+   :maxdepth: 1
+   
+   events/index
+
 Upgrading JupyterHub
 --------------------