oc_diagnostics.id_instrumentation module

oc_diagnostics.id_instrumentation module#

ID Instrumentation Helper#

This module rewrites Dash component IDs so that every interactive component receives a pattern-matching ID of the form:

id = {“event”: “<original-id>”}

This enables the UI event logger to capture all user interactions.

Instrumentation behavior is controlled by: - Global toggle: INSTRUMENTATION_ENABLED - Debug level: DEBUG_LEVELS[“INSTRUMENTATION”] (0–9)

Instrumentation is recursive and safe: - Structural IDs are never rewritten - Dict IDs are never rewritten - Components without IDs are skipped - Custom components may be included depending on debug level - Logging verbosity depends on instrumentation debug level

Responsibilities#

  • Recursively walk Dash component trees via the .children attribute.

  • Rewrite string IDs to {"event": "<original-id>"} when instrumentation is active.

  • Skip structural IDs (defined in STRUCTURAL_ID_PREFIXES and STRUCTURAL_ID_EXACT).

  • Skip dict IDs and components without an id attribute.

  • Delegate verbosity decisions to unified_debug helpers (instrumentation_verbose(), instrumentation_allow_custom_components()).

Diagnostics#

Domain: INSTRUMENTATION Levels:

L2 — lifecycle L3 — semantic details L4 — deep tracing

Contracts#

  • Structural IDs (root-group-*, tab-group-*, etc.) must never be rewritten.

  • Dict IDs must never be rewritten.

  • Must return the component unchanged when instrumentation_active() is False.

  • Must not raise; errors during ID rewriting are silently swallowed.

  • Must not recurse beyond MAX_INSTRUMENT_DEPTH (500) levels; a L1 diagnostic is emitted and the subtree is returned unchanged.

  • Standard Dash base-class components are always instrumented when active.

  • Custom (non-Dash-base-class) components are only instrumented when instrumentation_allow_custom_components() returns True (INSTRUMENTATION level ≥ 5). This prevents accidental ID rewriting of plain Python objects that happen to have a .id attribute.

oc_diagnostics.id_instrumentation.MAX_INSTRUMENT_DEPTH = 500#

Maximum recursion depth for instrument_ids.

Prevents RecursionError on pathologically deep component trees. A L1 diagnostic is emitted when the limit is reached and the subtree below that point is left uninstrumented. Real-world Dash applications rarely exceed 30–50 levels of nesting.

oc_diagnostics.id_instrumentation.instrument_ids(component, _depth: int = 0)[source]#

Recursively instrument Dash component IDs.

Behavior is controlled by unified_debug:

  • instrumentation_active():

    False → return component unchanged

  • instrumentation_verbose():

    True → log detailed recursion info False → log only high-level events

  • instrumentation_allow_custom_components():

    True → include custom (non-Dash-base-class) components False → only standard Dash base-class components are instrumented

Rules: - Instrument ANY component that has an ID stored in .id,

or in Dash internals (_props, _prop_ids).

  • Only rewrite string IDs (ignore dict IDs, None, etc.).

  • Skip structural IDs.

  • Recurse into children (list, tuple, or single child).

  • Stop recursion if depth exceeds MAX_INSTRUMENT_DEPTH.

oc_diagnostics.id_instrumentation.is_structural_id(cid)[source]#

Return True if this ID should NOT be instrumented.

Checks both the built-in structural-ID lists and any project-defined extensions loaded from global_settings.structural_id_prefixes / global_settings.structural_id_exact in debug_config.json (FS-02 / OI-17).