oc_diagnostics.instrumentation_middleware module

oc_diagnostics.instrumentation_middleware module#

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]).

oc_diagnostics.instrumentation_middleware.apply_instrumentation(component)[source]#

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

oc_diagnostics.instrumentation_middleware.enable_instrumentation_middleware(app: Dash)[source]#

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.

oc_diagnostics.instrumentation_middleware.patch_callback_dispatcher(app: Dash)[source]#

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.