| 1 |
Metadata-Version: 2.1 |
| 2 |
Name: jupyter-telemetry |
| 3 |
Version: 0.1.0 |
| 4 |
Summary: Jupyter telemetry library |
| 5 |
Home-page: http://jupyter.org |
| 6 |
Author: Jupyter Development Team |
| 7 |
Author-email: [email protected] |
| 8 |
License: BSD |
| 9 |
Description: # Telemetry |
| 10 |
|
| 11 |
[](https://circleci.com/gh/jupyter/telemetry) |
| 12 |
[](https://codecov.io/gh/jupyter/telemetry) |
| 13 |
[](https://jupyter-telemetry.readthedocs.io/en/latest/?badge=latest) |
| 14 |
|
| 15 |
*Telemetry for Jupyter Applications and extensions.* |
| 16 |
|
| 17 |
> Telemetry (təˈlemətrē): the process of recording and transmitting the readings of an instrument. [Oxford Dictionaries] |
| 18 |
|
| 19 |
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. |
| 20 |
|
| 21 |
## Install |
| 22 |
|
| 23 |
Jupyter's Telemetry library can be installed from PyPI. |
| 24 |
``` |
| 25 |
pip install jupyter_telemetry |
| 26 |
``` |
| 27 |
|
| 28 |
## Basic Usage |
| 29 |
|
| 30 |
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/). |
| 31 |
|
| 32 |
Let's look at a basic example of an `EventLog`. |
| 33 |
```python |
| 34 |
import logging |
| 35 |
from jupyter_telemetry import EventLog |
| 36 |
|
| 37 |
|
| 38 |
eventlog = EventLog( |
| 39 |
# Use logging handlers to route where events |
| 40 |
# should be record. |
| 41 |
handlers=[ |
| 42 |
logging.FileHandler('events.log') |
| 43 |
], |
| 44 |
# List schemas of events that should be recorded. |
| 45 |
allowed_schemas=[ |
| 46 |
'uri.to.event.schema' |
| 47 |
] |
| 48 |
) |
| 49 |
``` |
| 50 |
|
| 51 |
EventLog has two configurable traits: |
| 52 |
* `handlers`: a list of Python's `logging` handlers. |
| 53 |
* `allowed_schemas`: a list of event schemas to record. |
| 54 |
|
| 55 |
Event schemas must be registered with the `EventLog` for events to be recorded. An event schema looks something like: |
| 56 |
```json |
| 57 |
{ |
| 58 |
"$id": "url.to.event.schema", |
| 59 |
"title": "My Event", |
| 60 |
"description": "All events must have a name property.", |
| 61 |
"type": "object", |
| 62 |
"properties": { |
| 63 |
"name": { |
| 64 |
"title": "Name", |
| 65 |
"description": "Name of event", |
| 66 |
"type": "string" |
| 67 |
} |
| 68 |
}, |
| 69 |
"required": ["name"], |
| 70 |
"version": 1 |
| 71 |
} |
| 72 |
``` |
| 73 |
2 fields are required: |
| 74 |
* `$id`: a valid URI to identify the schema (and possibly fetch it from a remote address). |
| 75 |
* `version`: the version of the schema. |
| 76 |
|
| 77 |
The other fields follow standard JSON schema structure. |
| 78 |
|
| 79 |
Schemas can be registered from a Python `dict` object, a file, or a URL. This example loads the above example schema from file. |
| 80 |
```python |
| 81 |
# Register the schema. |
| 82 |
eventlog.register_schema_file('schema.json') |
| 83 |
``` |
| 84 |
|
| 85 |
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`. |
| 86 |
```python |
| 87 |
# Record an example event. |
| 88 |
event = {'name': 'example event'} |
| 89 |
eventlog.record_event( |
| 90 |
schema_id='url.to.event.schema', |
| 91 |
version=1, |
| 92 |
event=event |
| 93 |
) |
| 94 |
``` |
| 95 |
|
| 96 |
Keywords: Jupyter,JupyterLab |
| 97 |
Platform: Linux |
| 98 |
Platform: Mac OS X |
| 99 |
Platform: Windows |
| 100 |
Classifier: Intended Audience :: Developers |
| 101 |
Classifier: Intended Audience :: System Administrators |
| 102 |
Classifier: Intended Audience :: Science/Research |
| 103 |
Classifier: License :: OSI Approved :: BSD License |
| 104 |
Classifier: Programming Language :: Python |
| 105 |
Classifier: Programming Language :: Python :: 3 |
| 106 |
Requires-Python: >=3.5 |
| 107 |
Description-Content-Type: text/markdown |