add docs about sensitive data

docs/index.rst

@@ -98,8 +98,8 @@ Schemas can be registered from a Python dict object, a file, or a URL. This exam
    :maxdepth: 2
    :caption: Table of Contents:
 
-   pages/schemas.rst
-   pages/pii.rst
+   pages/schemas
+   pages/sensitive-data
 
 Indices and tables
 ------------------

docs/pages/schemas.rst

@@ -16,7 +16,14 @@ At a minimum, valid schemas should have the following keys:
 
     + ``title`` : name of the property
     + ``description``: documentation for this property.
-    + ``pii``: (optional) boolean for whether this property is personally identifiable information or not.
+    + ``level``: the level of sensitivity of this property.
+
+        Jupyter Telemetry provides four levels of sensitivity. The list of sensitivity level in increasing order:
+
+        + ``'unclassified'``
+        + ``'confidential'`` 
+        + ``'secret'``
+        + ``'top_secret'``
 
 - ``required``: list of required properties.
 
@@ -33,6 +40,7 @@ Here is a minimal example of a valid JSON schema for an event.
     properties:
       name:
         title: Name
+        level: confidential
         description: |
             Name of event
         type: string

docs/pages/sensitive-data.rst

@@ -0,0 +1,37 @@
+Logging sensitive data
+======================
+
+Jupyter Telemetry offers flexibility when logging and handling sensitive data. 
+
+Since events may include data with varying degrees of sensitivity, Jupyter Telemetry uses a multi-level security approach. It exposed four levels of sensitivity:
+
+    + ``'unclassified'``
+    + ``'confidential'``
+    + ``'secret'``
+    + ``'top_secret'``
+
+Each event property can be given one of these four levels. This is reflected in the event JSON schema using the ``level`` attribute (if this property is missing from the schema, an error will be thrown):
+
+.. code-block:: yaml
+
+    $id: example.schema
+    ...
+    properties:
+      name:
+        title: Name
+        level: confidential
+        description: |
+            Name of event
+        type: string
+
+Jupyter Telemetry uses the ``level`` attribute to drop sensitive data when emitting events. By default, properties greater than "unclassifed" are dropped from recorded event data.
+
+Each logging handler increase the level of sensitive data it emots. This can be configured by changing its ``.event_level`` attribute.
+
+.. code-block:: python
+
+    import logging
+
+    handler = logging.FileHandler('events.log')
+    handler.event_level = 'secret'
+