Metadata-Version: 2.1
Name: jupyter-telemetry
Version: 0.1.0
Summary: Jupyter telemetry library
Home-page: http://jupyter.org
Author: Jupyter Development Team
Author-email: jupyter@googlegroups.com
License: BSD
Description: # Telemetry
        
        [![CircleCI](https://circleci.com/gh/jupyter/telemetry.svg?style=svg)](https://circleci.com/gh/jupyter/telemetry)
        [![codecov](https://codecov.io/gh/jupyter/telemetry/branch/master/graph/badge.svg)](https://codecov.io/gh/jupyter/telemetry)
        [![Documentation Status](https://readthedocs.org/projects/jupyter-telemetry/badge/?version=latest)](https://jupyter-telemetry.readthedocs.io/en/latest/?badge=latest)
        
        *Telemetry for Jupyter Applications and extensions.*
        
        > Telemetry (təˈlemətrē): the process of recording and transmitting the readings of an instrument. [Oxford Dictionaries]
        
        Jupyter Telemetry enables Jupyter Applications (e.g. Jupyter Server, Jupyter Notebook, JupyterLab, JupyterHub, etc.) to record **events**—i.e. actions by application users—and transmit them to remote (or local) destinations as **structured** data. It works with Python's standard `logging` library to handle the transmission of events allowing users to send events to local files, over the web, etc.
        
        ## Install
        
        Jupyter's Telemetry library can be installed from PyPI.
        ```
        pip install jupyter_telemetry
        ```
        
        ## Basic Usage
        
        Telemetry provides a configurable traitlets object, `EventLog`, for structured event-logging in Python. It leverages Python's standard `logging` library for filtering, handling, and recording events. All events are validated (using [jsonschema](https://pypi.org/project/jsonschema/)) against registered [JSON schemas](https://json-schema.org/).
        
        Let's look at a basic example of an `EventLog`.
        ```python
        import logging
        from jupyter_telemetry import EventLog
        
        
        eventlog = EventLog(
            # Use logging handlers to route where events
            # should be record.
            handlers=[
                logging.FileHandler('events.log')
            ],
            # List schemas of events that should be recorded.
            allowed_schemas=[
                'uri.to.event.schema'
            ]
        )
        ```
        
        EventLog has two configurable traits:
        * `handlers`: a list of Python's `logging` handlers.
        * `allowed_schemas`: a list of event schemas to record.
        
        Event schemas must be registered with the `EventLog` for events to be recorded. An event schema looks something like:
        ```json
        {
          "$id": "url.to.event.schema",
          "title": "My Event",
          "description": "All events must have a name property.",
          "type": "object",
          "properties": {
            "name": {
              "title": "Name",
              "description": "Name of event",
              "type": "string"
            }
          },
          "required": ["name"],
          "version": 1
        }
        ```
        2 fields are required:
        * `$id`: a valid URI to identify the schema (and possibly fetch it from a remote address).
        * `version`: the version of the schema.
        
        The other fields follow standard JSON schema structure.
        
        Schemas can be registered from a Python `dict` object, a file, or a URL. This example loads the above example schema from file.
        ```python
        # Register the schema.
        eventlog.register_schema_file('schema.json')
        ```
        
        Events are recorded using the `record_event` method. This method validates the event data and routes the JSON string to the Python `logging` handlers listed in the `EventLog`.
        ```python
        # Record an example event.
        event = {'name': 'example event'}
        eventlog.record_event(
            schema_id='url.to.event.schema',
            version=1,
            event=event
        )
        ```
        
Keywords: Jupyter,JupyterLab
Platform: Linux
Platform: Mac OS X
Platform: Windows
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.5
Description-Content-Type: text/markdown
