oc_diagnostics.instrumentation_selftest_app module

oc_diagnostics.instrumentation_selftest_app module#

Instrumentation Self‑Test (Dash App)#

Purpose#

A minimal, deterministic Dash application used exclusively for manual validation of the instrumentation system:

  • ID rewriting (instrument_ids)

  • Dynamic instrumentation of callback outputs

  • UI event logger integration

  • Dispatcher patching (middleware)

  • Logging behavior under different debug-level modes

This module is NOT used in production and is intentionally verbose.

Warning

This is a manual integration harness, not an automated test. Running this module launches a Dash development server that blocks indefinitely until interrupted (Ctrl-C). It produces no assertions, no exit code, and no machine-readable result. It cannot be integrated into CI/CD pipelines. Use instrumentation_selftest_cli.py for headless, non-blocking instrumentation checks.

Lifecycle#

  1. Create Dash app

  2. Build static layout (UNINSTRUMENTED — IDs must remain strings)

  3. Register UI event logger

  4. Register callbacks

  5. Enable instrumentation middleware

  6. Run the development server (blocks until Ctrl-C)

Static layout must NOT be instrumented because Dash callback decorators match string IDs. Dynamic content is instrumented explicitly using:

return apply_instrumentation(dynamic_component_tree)

Debug-Level Modes#

MODE A — FORCE VERBOSE (default)

DEBUG_LEVELS[“INSTRUMENTATION”] = 9 DEBUG_LEVELS[“UI”] = 9

MODE B — RESPECT GLOBAL LEVELS

Use whatever levels are defined in unified_debug.py

Select mode via:

python -m oc_diagnostics.instrumentation_selftest_app –use-global

Responsibilities#

  • Build a static Dash layout with string IDs (NOT instrumented at build time, so callback decorators can match by string ID).

  • Register the UI event logger and all callbacks.

  • Enable instrumentation middleware via enable_instrumentation_middleware() after all callbacks are registered.

  • Optionally force maximum verbosity (default) or use global levels.

  • Launch the Dash development server (blocking call).

Diagnostics#

Domain: INSTRUMENTATION Levels:

L2 — lifecycle L3 — semantic details L4 — deep tracing

Contracts#

  • Must never be used in CI/CD or automated testing.

  • Must not instrument the static layout at build time.

  • Dynamic callback outputs must be instrumented via apply_instrumentation().

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

oc_diagnostics.instrumentation_selftest_app.create_test_app(force_verbose: bool)[source]#

Build the test app following the same lifecycle as the main app.

Parameters:

force_verbose (bool) – If True, override global debug levels and force maximum verbosity.

oc_diagnostics.instrumentation_selftest_app.main()[source]#

CLI entry point for the Dash instrumentation test app.