Debian Codegraph @

jupyter_telemetry.egg-info/PKG-INFO

raw
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 [![CircleCI](https://circleci.com/gh/jupyter/telemetry.svg?style=svg)](https://circleci.com/gh/jupyter/telemetry)
12 [![codecov](https://codecov.io/gh/jupyter/telemetry/branch/master/graph/badge.svg)](https://codecov.io/gh/jupyter/telemetry)
13 [![Documentation Status](https://readthedocs.org/projects/jupyter-telemetry/badge/?version=latest)](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