oc_diagnostics

oc_diagnostics#

Unified Debugging, Tracing, and Instrumentation for Option C Projects

oc_diagnostics is the official runtime diagnostics package for the Option C ecosystem.
It provides a unified debugging system, Dash‑aware instrumentation, callback middleware, a UI event logger, and a complete self‑test suite.

It is designed to be:

  • predictable

  • project‑agnostic

  • easy to integrate

  • fully configurable

  • compatible with any Option C project

OCT (Option C Tools) uses this package internally and re‑exports its public API.

Installation#

Core debugging only:

pip install oc_diagnostics

With Dash instrumentation:

pip install oc_diagnostics[dash]

Quickstart#

1. Add a project‑level diagnostics config#

Create:

diagnostics/debug_config.json

Example:

{
  "domains": {
    "DATA": { "level": 3, "color": "cyan" },
    "UI":   { "level": 4, "color": "blue" },
    "INSTRUMENTATION": 3
  },
  "global_settings": {
    "silent_mode": false,
    "enable_timestamps": true,
    "enable_colors": true,
    "include_filename": true,
    "output_mode": "both",
    "instrumentation_enabled": true
  }
}

2. Use _dbg in your code#

from oc_diagnostics import _dbg

def compute(x):
    func = "compute"
    _dbg("DATA", func, f"START x={x}", 2)
    return x * 2

3. Enable instrumentation in Dash apps#

from oc_diagnostics.instrumentation_middleware import enable_instrumentation_middleware
from oc_diagnostics.ui_event_logger import ui_event_logger

app = Dash(__name__)
app.layout = build_layout()  # static layout (uninstrumented)

ui_event_logger(app)
register_callbacks(app)
enable_instrumentation_middleware(app)

4. Instrument dynamic content#

from oc_diagnostics.instrumentation_middleware import apply_instrumentation

return apply_instrumentation(html.Div("Dynamic content"))

Features#

Unified Debugging#

  • _dbg(domain, func, message, level)

  • domain‑level filtering

  • timestamps

  • colorized output

  • filename + line number inclusion

  • stdout/stderr interception

  • uncaught exception logging

  • project‑owned configuration

Dash Instrumentation#

  • ID rewriting ({"event": "<id>"})

  • structural ID protection

  • recursive instrumentation

  • custom component support at higher debug levels

Middleware#

  • callback dispatcher patching

  • automatic instrumentation of callback outputs

UI Event Logger#

  • captures all user interactions

  • logs property changes (n_clicks, value, data, figure, selectedData)

Self‑Test Suite#

  • deterministic CLI tests

  • optional Dash app tests

  • validates ID rewriting, middleware, and event logging

Documentation#

Full documentation is included in the package:

  • Overview
    README.md

  • Architecture
    docs/ARCHITECTURE.md

  • Technical Reference
    docs/REFERENCE.md

  • Integration Guide
    docs/INTEGRATION_GUIDE.md

  • Release Notes
    docs/CHANGELOG.md

  • Opytion C Coding Style Specification docs/option_c_specs/00_Master_Option_C_Specs_Intro_V3_4.md (entry point) plus Core / Tooling / Diagnostics / AI Protocol / Changelog companion files in the same directory.

License#

MIT