oc_diagnostics.ui_event_logger module

oc_diagnostics.ui_event_logger module#

UI Event Logger#

Purpose#

Register a single Dash callback that captures all user interactions across an instrumented Dash application and routes every genuine event through _dbg().

Responsibilities#

  • Register a universal ALL-pattern Input callback that listens to n_clicks, value, data, figure, and selectedData on all instrumented components (those whose IDs were rewritten to {"event": "<original-id>"}).

  • Use ctx.triggered_prop_ids to build the set of (original_id, prop_name) pairs that actually triggered the current cycle, filtering out components that are non-None but did not change (e.g. a Dropdown holding its default selection).

  • Log each genuine user interaction via _dbg("UI", ..., override=True) so UI events always appear in the log regardless of domain debug levels.

  • Truncate large event values before logging (_MAX_EVENT_VALUE_LEN). For figure and data properties, log type + length summary unless DEBUG_LEVELS["UI"] >= 9.

  • Emit a clear L1 diagnostic warning when the required dcc.Store(id=REQUIRED_STORE_ID) component is absent from app.layout at registration time.

Diagnostics#

Domain: UI Levels:

L2 — lifecycle L3 — semantic details L4 — deep tracing

Contracts#

  • Must only log events that actually triggered the current callback cycle.

  • Must route all log output through _dbg() with override=True.

  • Requires Dash (pip install oc_diagnostics[dash]).

  • Must return no_update from the callback so the store is not dirtied.

  • Must not raise; logging failures must be silently swallowed.

  • Event values must be truncated to _MAX_EVENT_VALUE_LEN characters in repr() form before being passed to _dbg().

  • A L1 warning must be emitted when REQUIRED_STORE_ID is not found in app.layout at register_callbacks() time.

oc_diagnostics.ui_event_logger.REQUIRED_STORE_ID = 'debug-settings-data-store'#

The id of the dcc.Store component that the UI event logger callback writes to. This store must be present in the Dash layout before register_callbacks() is called; if it is absent Dash will raise a generic callback registration error at startup.

oc_diagnostics.ui_event_logger.register_callbacks(app)[source]#

Register the universal UI event logger callback.

This callback listens to the following properties on ALL components whose IDs were instrumented into {“event”: “<original-id>”}:

  • n_clicks

  • value

  • data

  • figure

  • selectedData

These cover all interactive Dash components:

Buttons, Dropdowns, Inputs, Checklists, Sliders, Stores, Graphs, Tabs, etc.

Dash requires explicit property names (no ALL wildcard allowed), so we register one Input() per property.

Prerequisites#

The layout must contain dcc.Store(id=REQUIRED_STORE_ID, ...). A L1 warning is emitted at registration time when this component is not found.

Note

The ui_event_properties setting is read once at callback registration time. Changes to global_settings.ui_event_properties (via config hot-reload or set_global_setting()) will NOT be picked up by an already-registered callback — a full application restart is required.

oc_diagnostics.ui_event_logger.ui_event_logger(app)[source]#

Convenience wrapper to match existing usage.