Skip to content
Configurable event-logging for Jupyter applications and extensions.
Python TypeScript
Branch: master
Clone or download
Zsailer Merge pull request #36 from Zsailer/0.0.4
bump version to 0.0.4
Latest commit c8b1ead Jan 17, 2020
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci
docs
jupyter_telemetry
proposal
src
tests
.gitignore
CHANGELOG.md
LICENSE
MANIFEST.in
README.md add RTD badge Oct 7, 2019
dev-requirements.txt Setup flake8 and fix linter errors Jul 19, 2019
package.json
requirements.txt rearrange telemetry repo for initial setup Jul 4, 2019
setup.cfg
setup.py

README.md

Telemetry

CircleCI codecov Documentation Status

Telemetry for Jupyter Applications and extensions.

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) against registered JSON schemas.

Let's look at a basic example of an EventLog.

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:

{
  "$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.

# 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.

# Record an example event.
event = {'name': 'example event'}
eventlog.record_event(
    schema_id='url.to.event.schema',
    version=1,
    event=event
)
You can’t perform that action at this time.