# Telemetry
[](https://circleci.com/gh/jupyter/telemetry)
[](https://codecov.io/gh/jupyter/telemetry)
[](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
)
```
Raw data
{
"_id": null,
"home_page": "http://jupyter.org",
"name": "jupyter-telemetry",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.5",
"maintainer_email": "",
"keywords": "Jupyter,JupyterLab",
"author": "Jupyter Development Team",
"author_email": "jupyter@googlegroups.com",
"download_url": "https://files.pythonhosted.org/packages/c4/59/edd04590235d9afe2b2b49ec449c6146dc71b717110f4a1034d52eb54303/jupyter_telemetry-0.1.0.tar.gz",
"platform": "Linux",
"description": "# Telemetry\n\n[](https://circleci.com/gh/jupyter/telemetry)\n[](https://codecov.io/gh/jupyter/telemetry)\n[](https://jupyter-telemetry.readthedocs.io/en/latest/?badge=latest)\n\n*Telemetry for Jupyter Applications and extensions.*\n\n> Telemetry (t\u0259\u02c8lem\u0259tr\u0113): the process of recording and transmitting the readings of an instrument. [Oxford Dictionaries]\n\nJupyter Telemetry enables Jupyter Applications (e.g. Jupyter Server, Jupyter Notebook, JupyterLab, JupyterHub, etc.) to record **events**\u2014i.e. actions by application users\u2014and 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.\n\n## Install\n\nJupyter's Telemetry library can be installed from PyPI.\n```\npip install jupyter_telemetry\n```\n\n## Basic Usage\n\nTelemetry 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/).\n\nLet's look at a basic example of an `EventLog`.\n```python\nimport logging\nfrom jupyter_telemetry import EventLog\n\n\neventlog = EventLog(\n # Use logging handlers to route where events\n # should be record.\n handlers=[\n logging.FileHandler('events.log')\n ],\n # List schemas of events that should be recorded.\n allowed_schemas=[\n 'uri.to.event.schema'\n ]\n)\n```\n\nEventLog has two configurable traits:\n* `handlers`: a list of Python's `logging` handlers.\n* `allowed_schemas`: a list of event schemas to record.\n\nEvent schemas must be registered with the `EventLog` for events to be recorded. An event schema looks something like:\n```json\n{\n \"$id\": \"url.to.event.schema\",\n \"title\": \"My Event\",\n \"description\": \"All events must have a name property.\",\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"title\": \"Name\",\n \"description\": \"Name of event\",\n \"type\": \"string\"\n }\n },\n \"required\": [\"name\"],\n \"version\": 1\n}\n```\n2 fields are required:\n* `$id`: a valid URI to identify the schema (and possibly fetch it from a remote address).\n* `version`: the version of the schema.\n\nThe other fields follow standard JSON schema structure.\n\nSchemas can be registered from a Python `dict` object, a file, or a URL. This example loads the above example schema from file.\n```python\n# Register the schema.\neventlog.register_schema_file('schema.json')\n```\n\nEvents 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`.\n```python\n# Record an example event.\nevent = {'name': 'example event'}\neventlog.record_event(\n schema_id='url.to.event.schema',\n version=1,\n event=event\n)\n```\n\n\n",
"bugtrack_url": null,
"license": "BSD",
"summary": "Jupyter telemetry library",
"version": "0.1.0",
"project_urls": {
"Homepage": "http://jupyter.org"
},
"split_keywords": [
"jupyter",
"jupyterlab"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "90ab8d565a0797dacf82dea161ba5c40bd1f3ddbf365e3f7f8fd63007f03b19f",
"md5": "a4c9f286d496242b0d48436ac950ffde",
"sha256": "1de3e423b23aa40ca4a4238d65c56dda544061ff5aedc3f7647220ed7e3b9589"
},
"downloads": -1,
"filename": "jupyter_telemetry-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a4c9f286d496242b0d48436ac950ffde",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.5",
"size": 7058,
"upload_time": "2020-04-10T16:32:01",
"upload_time_iso_8601": "2020-04-10T16:32:01.302076Z",
"url": "https://files.pythonhosted.org/packages/90/ab/8d565a0797dacf82dea161ba5c40bd1f3ddbf365e3f7f8fd63007f03b19f/jupyter_telemetry-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c459edd04590235d9afe2b2b49ec449c6146dc71b717110f4a1034d52eb54303",
"md5": "578a8787b59d1d68924e8597e4300398",
"sha256": "445c613ae3df70d255fe3de202f936bba8b77b4055c43207edf22468ac875314"
},
"downloads": -1,
"filename": "jupyter_telemetry-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "578a8787b59d1d68924e8597e4300398",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.5",
"size": 9607,
"upload_time": "2020-04-10T16:32:02",
"upload_time_iso_8601": "2020-04-10T16:32:02.698912Z",
"url": "https://files.pythonhosted.org/packages/c4/59/edd04590235d9afe2b2b49ec449c6146dc71b717110f4a1034d52eb54303/jupyter_telemetry-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2020-04-10 16:32:02",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "jupyter-telemetry"
}
JSON