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.register_callbacks |
( |
| app | ) |
|
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.
Definition at line 173 of file ui_event_logger.py.
1.15.0