Registry / observability / jupyter-events

jupyter-events

JSON →
library0.12.1pypypi✓ verified 25d ago

Jupyter Events is an event system library that enables Jupyter Python applications (e.g., Jupyter Server, JupyterLab Server, JupyterHub) and extensions to emit structured data describing internal happenings. Other software can then listen and respond to these events. The current version is 0.12.0, with releases occurring periodically to introduce new features, improvements, and bug fixes.

pip install jupyter_events
INSTALL
IMPORT
SIG · JUPYTER-EVENTS
J
jupyter-events
observabilitypythonv0.12.1
Install
3.7s avg
Import
6108ms
Disk
31MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.12.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 6.342s · 32MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 3.7s · import 5.874s · 33MB
31MB installed
● package 31MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

EventLogger
from jupyter_events import EventLogger

This quickstart demonstrates how to initialize an `EventLogger`, register a custom event schema, emit an event conforming to that schema, and verify that the event is logged. Events are validated against registered JSON schemas before being processed by Python's standard logging handlers.

import logging from jupyter_events import EventLogger import json import os # Define a simple event schema (in-memory for this example) my_event_schema = { "$id": "https://example.com/schemas/my_event.json", "title": "My Custom Event", "description": "A simple custom event for demonstration.", "type": "object", "properties": { "message": {"type": "string"}, "level": {"type": "string", "enum": ["info", "warning", "error"]} }, "required": ["message", "level"] } # Create a temporary log file event_log_file = 'quickstart_events.log' # Initialize EventLogger with a FileHandler and register the schema logger = EventLogger( handlers=[logging.FileHandler(event_log_file)], allowed_schemas=[my_event_schema["$id"]] ) logger.register_event_schema(my_event_schema) # Emit an event print(f"Emitting an 'info' event...") logger.emit(schema_id=my_event_schema["$id"], data={'message': 'This is a test event!', 'level': 'info'}) print(f"Event emitted to {event_log_file}") # Read the logged event with open(event_log_file, 'r') as f: logged_event = json.loads(f.readline()) print(f"Logged event: {logged_event}") # Clean up the log file os.remove(event_log_file)
Debug
Known issues
breakingApplications previously using `jupyter-telemetry` (e.g., JupyterHub) must migrate to `jupyter-events`. The API for event emission and schema definition is different and direct compatibility is not maintained.
fix
Review `jupyter-events` documentation for equivalent functionalities and update event emission calls and schema definitions. Consult the changelog of dependent applications (like JupyterHub) for specific migration guides.
affects: N/A (migration from jupyter-telemetry)
gotchaEvent schemas must be explicitly registered with the `EventLogger` using `register_event_schema()` before emitting events. If an event is emitted for an unregistered schema ID, it will not be recorded and may raise an error or be silently dropped depending on the `EventLogger`'s configuration or version.
fix
Always call `event_logger.register_event_schema(your_schema_dict)` for each schema ID that your application intends to emit events for. Ensure the `$id` field in your schema dictionary matches the `schema_id` used in `emit()` calls.
affects: All versions
gotchaSensitive data in event payloads requires careful handling, especially if event data is routed to client applications or persistent storage. While `jupyter-events` allows for redaction policies, an incorrect or missing policy could expose sensitive information.
fix
Define and apply appropriate redaction policies within your event schemas. Thoroughly test event flows to ensure sensitive data is not inadvertently exposed or logged in plaintext, especially when integrating with client-side listeners or external logging services.
affects: All versions
breakingEvent schemas submitted for registration must conform to the `jupyter-events` meta-schema. Specifically, they must include top-level `version`, `$id`, and `properties` fields. Failure to include these required properties will result in a `jsonschema.exceptions.ValidationError` during schema registration.
fix
Ensure your event schema dictionary includes the `version`, `$id`, and `properties` fields at the root level. For example:
```json
{
  "$id": "https://example.com/schemas/my_event.json",
  "version": "1",
  "title": "My Custom Event",
  "description": "A simple custom event for demonstration.",
  "type": "object",
  "properties": {
    "message": {"type": "string"},
    "level": {"type": "string", "enum": ["info", "warning", "error"]}
  },
  "required": ["message", "level"]
}
```
affects: All versions
gotchaEvent schemas registered with `jupyter-events` must conform to the `jupyter-events` meta-schema. This meta-schema requires specific top-level properties like `$id`, `version`, and `properties` to be present. Omitting a required meta-schema property will result in a `jsonschema.exceptions.ValidationError` during schema registration.
fix
Ensure your event schema dictionary includes all required top-level fields such as `$id`, `version` (e.g., `'version': '1'`), and `properties` as specified by the `jupyter-events` meta-schema. Consult the `jupyter-events` documentation for the full meta-schema specification.
affects: All versions
Errors
Common errors & fixes
TypeError: create.<locals>.Validator.__init__() got an unexpected keyword argument 'registry'
This error occurs due to an incompatibility between `jupyter-events` and newer versions of its `jsonschema` dependency, where the `Validator` class in `jsonschema` no longer accepts the `registry` argument that `jupyter-events` expects.
fix
Downgrade `jsonschema` to a compatible version (e.g., `jsonschema==4.19.2`) or upgrade `jupyter-events` to its latest version, which may have resolved the dependency conflict.
JupyterEventsVersionWarning: The `version` property of an event schema must be a string. It has been type coerced, but in a future version of this library, it will fail to validate. Please update schema: <schema_url>
An event schema being used by `jupyter-events` has its `version` property defined with a non-string type, which is deprecated and will lead to validation errors in future library versions.
fix
Modify the event schema to ensure the `version` property is explicitly a string type.
ModuleNotFoundError: No module named 'jupyter_events'
The `jupyter_events` package is either not installed in the Python environment that Jupyter is currently using, or there is a discrepancy between the environment where the package was installed and the active Jupyter kernel's environment.
fix
Install `jupyter-events` using `pip install jupyter_events` (or `conda install -c conda-forge jupyter_events` if using Anaconda) in the correct Python environment, and then restart your Jupyter kernel or server.
ValidationError: '$id' is a required property
This error indicates that an event schema being registered or validated by `jupyter-events` is missing the mandatory `'$id'` key, which is required for identifying the schema.
fix
Ensure all event schemas include a unique `"$id"` property, which should be a valid URI, to correctly identify the schema.
ValidationError: 'version' is a required property
This error signifies that an event schema being registered or validated by `jupyter-events` lacks the mandatory `'version'` key, which is essential for schema versioning.
fix
Ensure all event schemas include a `"version"` property with a string value to specify the schema's version.
Upgrade
Version history
0.12.1latest on PyPI · released Apr 20, 2026
Audit
Dependencies
jsonschemarequiredUsed for validating event data against registered JSON schemas.
python_json_loggerrequiredUsed for formatting logs as JSON strings.
pyyamlrequiredLikely used for loading or parsing schema definitions.
referencingrequiredJSON Referencing + Python, likely for schema resolution.
rfc3339_validatorrequiredA pure Python RFC3339 validator, likely for date/time string validation in schemas.
Agent activity
30 hits · last 30 days
node
26
OpenAI (training)
2
Resources