Functions
	apply_instrumentation (component)
	patch_callback_dispatcher (Dash app)
	enable_instrumentation_middleware (Dash app)

Detailed Description

Instrumentation Middleware
==========================

Purpose
-------
Provide a single entry point (``apply_instrumentation``) for applying
recursive ID instrumentation to any Dash component tree, and a dispatcher
patch (``patch_callback_dispatcher``) that automatically instruments all
callback output trees via Dash's ``callback_map``.

Responsibilities
----------------
- ``apply_instrumentation()``: call ``instrument_ids()`` if instrumentation
  is active; return the component unchanged otherwise.
- ``patch_callback_dispatcher()``: wrap every callback in
  ``app.callback_map`` with a thin shim that passes its return value
  through ``apply_instrumentation()``.  Never double-wraps a callback.
- ``enable_instrumentation_middleware()``: single-call initialization
  entry point for app setup code; call once after all callbacks are
  registered.
- Log diagnostic events through ``_dbg()`` at appropriate levels.

Diagnostics
-----------
Domain: INSTRUMENTATION
Levels:
    L2 — lifecycle
    L3 — semantic details
    L4 — deep tracing

Contracts
---------
- ``apply_instrumentation()`` must be a no-op when
  ``instrumentation_active()`` is ``False``.
- ``patch_callback_dispatcher()`` must never double-wrap a callback that
  is already wrapped (guarded by ``_is_instrumentation_wrapper`` flag).
- Must not modify the component tree when instrumentation is disabled.
- Requires Dash (``pip install oc_diagnostics[dash]``).

Function Documentation

◆ apply_instrumentation()

oc_diagnostics.instrumentation_middleware.apply_instrumentation ( component )

Apply ID instrumentation to a component tree *if enabled*.

- No manual recursion (instrument_ids handles that)
- No structural ID rewrites
- Logs only when instrumentation debug level is high enough

Definition at line 59 of file instrumentation_middleware.py.

Here is the caller graph for this function:

◆ enable_instrumentation_middleware()

oc_diagnostics.instrumentation_middleware.enable_instrumentation_middleware ( Dash app )

Call this once after:

- The app is created
- The layout is assigned
- All callbacks (including UI event logger) are registered

This matches the lifecycle that already works in the main app.

Definition at line 148 of file instrumentation_middleware.py.

Here is the call graph for this function:

◆ patch_callback_dispatcher()

oc_diagnostics.instrumentation_middleware.patch_callback_dispatcher ( Dash app )

Wrap all callbacks in app.callback_map so that their outputs
are automatically passed through apply_instrumentation().

This is the mechanism already proven to work in the main app.

Definition at line 84 of file instrumentation_middleware.py.