Classes
class	_StreamInterceptor

Functions
str	_safe_env_path (str name)
	_load_debug_config ()
str	_get_log_file ()
str	_get_timestamp ()
str	_get_color (str domain, int level)
str	_reset_color ()
None	_prune_old_log_files (str log_dir, int max_count)
	_ensure_log_dir_and_header ()
	_write_to_file (str line)
str	_apply_redaction (str text)
	_emit (str line, int level, dict\|None record=None)
	_dbg (str domain, str func, str msg, int\|str\|None level=None, bool override=False, int _depth=1)
	_dbg_ai_trace (str domain, str func, str msg, int _depth=1)
None	_adbg (str domain, str func, str msg, int\|None level=None, bool override=False)
bool	instrumentation_active ()
bool	instrumentation_verbose ()
bool	instrumentation_allow_custom_components ()
bool	instrumentation_allow_all ()
None	set_debug_level (str domain, int level)
None	set_global_setting (str key, value)
	dbg_timed (str domain, str func, str label="", int level=3)
	dbg_scope (str domain, str func, str label="", int level=2)
	dbg_profile (str domain="GENERAL", str func="", str label="", int level=3)
None	_dbg_assert (str domain, condition, str message, str\|None func=None)
	dbg_trace (str domain, int level=2)
	dbg_metrics (str domain, int level=3)
	_exception_hook (exc_type, exc_value, exc_traceback)
None	_reload_config ()
None	_watch_config_loop ()
None	init (bool intercept_streams=True, bool intercept_exceptions=True, bool watch_config=False)

Variables
dict	_COLOR_NAME_MAP
dict	_DOMAIN_SCHEMA
dict	_CONFIG_SCHEMA
str	_CONFIG_PATH = ""
float	_CONFIG_MTIME = 0.0
int	_MAX_ENV_PATH_LEN = 4096
int	_MAX_CONFIG_BYTES = 10 * 1024 * 1024
	_levels
	_colors
	_settings
	_config_source
	DEBUG_LEVELS = _levels
	COLOR_CODES = _colors
	CONFIG_SOURCE = _config_source
	INSTRUMENTATION_ENABLED = _settings["instrumentation_enabled"]
	SILENT_MODE = _settings["silent_mode"]
tuple	ADDITIONAL_STRUCTURAL_PREFIXES
frozenset	ADDITIONAL_STRUCTURAL_EXACT
	ENABLE_TIMESTAMPS = _settings["enable_timestamps"]
	ENABLE_COLORS = _settings["enable_colors"]
	INCLUDE_FILENAME = _settings["include_filename"]
	OUTPUT_MODE = _settings["output_mode"]
int	MAX_LOG_FILES = _settings["max_log_files"]
tuple	MAX_LOG_SIZE_BYTES
frozenset	HTTP_REDACT_HEADERS
bool	INSTRUMENTATION_ALL = _settings.get("instrumentation_allow_all", False)
tuple	_DEFAULT_UI_EVENT_PROPERTIES
tuple	UI_EVENT_PROPERTIES
tuple	PROD_MODE
int	PROD_MAX_LEVEL = int(_settings.get("prod_max_level", 2))
set	_prod_downgrade_warned = set()
bool	AI_TRACE_ENABLED = bool(_settings.get("ai_trace_level", False))
	_env_level = os.environ.get("OC_DIAGNOSTICS_LEVEL", "").strip()
	_env_level_int = int(_env_level)
list	REDACTION_PATTERNS = []
bool	REDACT_SECRETS = bool(_settings.get("redact_secrets", True))
re	_GIT_URL_RE
re	_TOKEN_PREFIXES_RE
re	_KV_SECRET_RE
str	LOG_DIR = _safe_env_path("OC_DIAGNOSTICS_LOG_DIR") or os.path.join(os.getcwd(), "logs")
str	_env_log_file = _safe_env_path("OC_DIAGNOSTICS_LOG_FILE")
	_config_log_file_path = _settings.get("log_file_path")
str	LOG_FILE = _env_log_file or _config_log_file_path or None
	ORIGINAL_STDOUT = sys.stdout
	ORIGINAL_STDERR = sys.stderr
bool	_header_written = False
	_log_lock = threading.Lock()
	_ANSI_ESCAPE_RE
	_original_excepthook = None
	_interceptor_active = threading.local()
bool	_initialized = False
bool	_init_warned = False
bool	_io_fallback_warned = False

Detailed Description

Unified Debugging System
========================

Purpose
-------
Provide a single, centralized ``_dbg()`` debug logger for Option C projects,
together with per-domain level filtering, ANSI color output, timestamped log
files, stdout/stderr interception, and an uncaught-exception hook.

Responsibilities
----------------
- Load debug configuration from ``diagnostics/debug_config.json`` (project
  root) or the bundled fallback, recording ``CONFIG_SOURCE`` for the log header.
- Provide ``_dbg()`` with domain/level filtering, caller-site reporting, and
  optional override mode.
- Write formatted output to terminal (ANSI colors retained) and/or a log file
  (all ANSI escape sequences stripped) based on ``OUTPUT_MODE``.
- Provide ``_StreamInterceptor`` wrapping ``sys.stdout``/``sys.stderr`` with a
  full ``io.TextIOBase``-compatible interface and a thread-local re-entrant
  recursion guard.
- Provide ``init()`` to activate stream interception and the exception hook
  explicitly; importing this module has zero side effects.
- Provide ``instrumentation_active()``, ``instrumentation_verbose()``, and
  ``instrumentation_allow_custom_components()`` helpers consumed by other modules.

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

Contracts
---------
- Importing this module must have zero side effects on ``sys.stdout``,
  ``sys.stderr``, or ``sys.excepthook``.
- ``init()`` must be idempotent; calling it more than once is a no-op.
- ``_dbg()`` must never raise; all internal errors are silently swallowed.
- ``CONFIG_SOURCE`` must be a non-empty string after module load.

Configuration
-------------
Debug domains, levels, colors, and global settings are loaded from
`diagnostics/debug_config.json` in the project root if present, or from
`debug_config.json` in the same directory as this module as a fallback.

Each project supplies its own `diagnostics/debug_config.json` with
project-specific domains. This keeps the library project-independent.

Environment Variables
---------------------
``OC_DIAGNOSTICS_CONFIG``
    Absolute path to a ``debug_config.json`` file.  When set, this path is
    used instead of ``<cwd>/diagnostics/debug_config.json``.  Useful for
    embedded usage, subprocess invocation, or CI environments where the
    working directory is not the project root.

``OC_DIAGNOSTICS_LOG_DIR``
    Absolute path to the directory where log files are written.  When set,
    this replaces the default ``<cwd>/logs`` directory.

``UNIFIED_DEBUG_DISABLE_EXCEPTION_HOOK``
    Set to ``1`` to prevent ``init()`` from installing the custom
    ``sys.excepthook``, even when ``intercept_exceptions=True`` is passed.
    Useful in environments (pytest, debuggers, ASGI frameworks) that install
    their own exception handlers and must not be displaced.

Log Format
----------
When filename inclusion is enabled:

    [DOMAIN][L2][file.py:123::caller=foo|logical context=bar] 14:03:12.345 Message...

When disabled:

    [DOMAIN][L2][logical context=bar] 14:03:12.345 Message...

Function Documentation

◆ _adbg()

None oc_diagnostics.unified_debug._adbg	(	str	domain,
		str	func,
		str	msg,
		int \| None	level = None,
		bool	override = False )

protected

Async variant of _dbg().

Terminal output is written synchronously (fast, low-latency).
File I/O is offloaded to a thread via asyncio.to_thread() so that
async callers are not blocked by disk writes.

The caller frame is captured *synchronously* before any await because
frame references become invalid once the coroutine is suspended.

Definition at line 877 of file unified_debug.py.

Here is the call graph for this function:

◆ _apply_redaction()

str oc_diagnostics.unified_debug._apply_redaction ( str text )

protected

Apply configured redaction patterns to log output (production mode only).

OI-506 / FS-506 layer order (production mode):

1. Built-in secret/URL/token scrubbers (gated by ``REDACT_SECRETS``):
   git ``user:token@`` credentials, common token prefixes (``ghp_``,
   ``sk-``, ``xoxb-``, ``eyJ``...), and ``secret=value`` KV pairs.
2. User-defined ``REDACTION_PATTERNS`` from config.

The built-ins run unconditionally when ``REDACT_SECRETS`` is True so
production logs cannot leak credentials even if the operator forgot
to configure a pattern list. The toggle exists purely as an escape
hatch for environments that redact at the shipping layer instead.

Definition at line 674 of file unified_debug.py.

Here is the caller graph for this function:

◆ _dbg()

oc_diagnostics.unified_debug._dbg	(	str	domain,
		str	func,
		str	msg,
		int \| str \| None	level = None,
		bool	override = False,
		int	_depth = 1 )

protected

Unified debug logger.

Parameters
----------
domain : str
    Debug domain (e.g., "CONTROLLER", "AHK", "MODE").
func : str
    Logical context name provided by the caller.
msg : str
    Message text.
level : int | str | None
    Debug level (0-9), or ``"ai_trace"`` for AI-Trace shadow logging.
    Defaults to 2.
override : bool
    If True, bypasses domain-level filtering.

Behavior
--------
- Automatically captures filename, line number, and caller function.
- Formats output according to INCLUDE_FILENAME and ENABLE_TIMESTAMPS.
- Writes to terminal, file, or both.
- When ``level="ai_trace"``: writes to file/JSONL only (no console output).
  Requires ``ai_trace_level: true`` in config; otherwise silently discarded.

Definition at line 727 of file unified_debug.py.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ _dbg_ai_trace()

oc_diagnostics.unified_debug._dbg_ai_trace	(	str	domain,
		str	func,
		str	msg,
		int	_depth = 1 )

protected

Write an AI-Trace message to file/JSONL only (never console).

Called internally by ``_dbg()`` when ``level="ai_trace"``.

Definition at line 838 of file unified_debug.py.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ _dbg_assert()

None oc_diagnostics.unified_debug._dbg_assert	(	str	domain,
			condition,
		str	message,
		str \| None	func = None )

protected

Domain-aware runtime assertion, suppressed in production mode.

Parameters
----------
domain : str
    Debug domain for the assertion message.
condition
    Expression to evaluate.  If falsy (and not in production mode),
    emits an L1 override ``_dbg`` message and raises ``AssertionError``.
message : str
    Descriptive failure message.
func : str | None
    Logical context name.  If ``None``, uses ``"<unknown>"``.

Notes
-----
In ``PROD_MODE`` this function returns immediately on entry; no
assertion check is performed, no ``_dbg`` is emitted, and no
``AssertionError`` is raised.  Argument expressions (including
``condition`` and ``message``) are still evaluated by Python before
the call enters this function — do not pass expensive computations
as arguments.  **Never** use for safety-critical invariants — see §6a
and AP-16 in the specification.

Definition at line 1088 of file unified_debug.py.

Here is the call graph for this function:

◆ _emit()

oc_diagnostics.unified_debug._emit	(	str	line,
		int	level,
		dict \| None	record = None )

protected

Definition at line 700 of file unified_debug.py.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ _ensure_log_dir_and_header()

oc_diagnostics.unified_debug._ensure_log_dir_and_header ( )

protected

Definition at line 599 of file unified_debug.py.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ _exception_hook()

oc_diagnostics.unified_debug._exception_hook	(	exc_type,
		exc_value,
		exc_traceback )

protected

Definition at line 1231 of file unified_debug.py.

Here is the call graph for this function:

◆ _get_color()

str oc_diagnostics.unified_debug._get_color	(	str	domain,
		int	level )

protected

Definition at line 572 of file unified_debug.py.

Here is the caller graph for this function:

◆ _get_log_file()

str oc_diagnostics.unified_debug._get_log_file ( )

protected

Return the LOG_FILE path, computing it on the first call.

Always invoked from within a ``_log_lock``-protected block so the lazy
one-time initialization is thread-safe.  After the first call ``LOG_FILE``
is a non-None string and subsequent calls are a single None-check.

Definition at line 535 of file unified_debug.py.

Here is the caller graph for this function:

◆ _get_timestamp()

str oc_diagnostics.unified_debug._get_timestamp ( )

protected

Definition at line 565 of file unified_debug.py.

Here is the caller graph for this function:

◆ _load_debug_config()

oc_diagnostics.unified_debug._load_debug_config ( )

protected

Load debug_config.json from the project diagnostics/ directory if present,
otherwise fall back to debug_config.json next to this module.

Returns (domains_dict, color_codes_dict, global_settings_dict, config_source_str).
Falls back to minimal defaults if the file is missing or invalid.
config_source_str describes which file was loaded, or why defaults were used.

Definition at line 200 of file unified_debug.py.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ _prune_old_log_files()

None oc_diagnostics.unified_debug._prune_old_log_files	(	str	log_dir,
		int	max_count )

protected

Delete the oldest log files when the count exceeds max_count. (FS-06)

Definition at line 584 of file unified_debug.py.

Here is the caller graph for this function:

◆ _reload_config()

None oc_diagnostics.unified_debug._reload_config ( )

protected

Reload debug_config.json in-place, updating all module-level globals.

Preserves the existing ``DEBUG_LEVELS`` dict *object* so that downstream
modules holding a reference to the dict automatically see the updated levels.

Uses an update-first, prune-stale-after pattern (OI-29) to avoid the brief
empty-dict window that ``clear()`` + ``update()`` would create.

Definition at line 1386 of file unified_debug.py.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ _reset_color()

str oc_diagnostics.unified_debug._reset_color ( )

protected

Definition at line 580 of file unified_debug.py.

Here is the caller graph for this function:

◆ _safe_env_path()

str oc_diagnostics.unified_debug._safe_env_path ( str name )

protected

Return ``os.environ[name]`` if it passes OI-515 sanity checks.

Returns an empty string when the env var is unset, empty, contains a
NUL byte, or exceeds :data:`_MAX_ENV_PATH_LEN`. A warning is emitted
in the length/NUL-byte case so operators notice the rejection.

Definition at line 167 of file unified_debug.py.

Here is the caller graph for this function:

◆ _watch_config_loop()

None oc_diagnostics.unified_debug._watch_config_loop ( )

protected

Daemon thread: poll the config file mtime every 2 s; reload on change. (FS-09)

Definition at line 1441 of file unified_debug.py.

Here is the call graph for this function:

◆ _write_to_file()

oc_diagnostics.unified_debug._write_to_file ( str line )

protected

Definition at line 638 of file unified_debug.py.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ dbg_metrics()

oc_diagnostics.unified_debug.dbg_metrics	(	str	domain,
		int	level = 3 )

Decorator that logs structured performance metrics (time + memory).

Emits a JSON-style string with ``duration_ms`` and ``memory_mb`` fields
suitable for observability tooling.

Parameters
----------
domain : str
    Debug domain for the metrics message.
level : int
    Debug level (default 3).

Definition at line 1173 of file unified_debug.py.

Here is the call graph for this function:

◆ dbg_profile()

oc_diagnostics.unified_debug.dbg_profile	(	str	domain = "GENERAL",
		str	func = "",
		str	label = "",
		int	level = 3 )

Decorator that wraps a function with :func:`dbg_timed`.

Example::

    @dbg_profile("CONTROLLER", label="fetch_data")
    def fetch_data():
        ...

Definition at line 1064 of file unified_debug.py.

Here is the call graph for this function:

◆ dbg_scope()

oc_diagnostics.unified_debug.dbg_scope	(	str	domain,
		str	func,
		str	label = "",
		int	level = 2 )

Context manager that logs ENTER and EXIT at the specified level without timing.

Use for pure lifecycle tracing where elapsed time is not needed.
For timed tracing, use :func:`dbg_timed` instead.

Example::

    with dbg_scope("DATA", "load_records"):
        result = expensive_operation()

Definition at line 1045 of file unified_debug.py.

Here is the call graph for this function:

◆ dbg_timed()

oc_diagnostics.unified_debug.dbg_timed	(	str	domain,
		str	func,
		str	label = "",
		int	level = 3 )

Context manager that logs ENTER and EXIT with elapsed time in milliseconds.

Example::

    with dbg_timed("CONTROLLER", "my_func", label="heavy_op"):
        do_work()

Definition at line 1026 of file unified_debug.py.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ dbg_trace()

oc_diagnostics.unified_debug.dbg_trace	(	str	domain,
		int	level = 2 )

Decorator that emits START/END lifecycle messages and catches exceptions.

Injects a ``func`` local variable set to the decorated function's
``__name__`` so that inner ``_dbg`` calls can reference it without
hardcoding a string.

Parameters
----------
domain : str
    Debug domain for lifecycle messages.
level : int
    Debug level for START/END messages (default 2).

Example
-------
::

    @dbg_trace("DATA")
    def process_data(data):
        _dbg("DATA", func, "working...", 3)
        return transform(data)

Definition at line 1130 of file unified_debug.py.

Here is the call graph for this function:

◆ init()

None oc_diagnostics.unified_debug.init	(	bool	intercept_streams = True,
		bool	intercept_exceptions = True,
		bool	watch_config = False )

Initialize oc_diagnostics side effects.

Must be called explicitly after importing oc_diagnostics.
Importing the package does NOT activate stream interception or
the custom exception hook automatically.

Parameters
----------
intercept_streams : bool
    If True, replace sys.stdout and sys.stderr with _StreamInterceptor
    instances that route all print() calls through _dbg().
    Can also be disabled by setting the environment variable
    UNIFIED_DEBUG_DISABLE_STDIO_INTERCEPT=1 before calling init().
    Forced to False in production mode (PROD_MODE=True).  Default True.
intercept_exceptions : bool
    If True, install a custom sys.excepthook that logs uncaught
    exceptions through _dbg() and then delegates to the previously
    active hook. Can also be disabled by setting the environment
    variable UNIFIED_DEBUG_DISABLE_EXCEPTION_HOOK=1 before calling
    init(). Forced to False in production mode (PROD_MODE=True).
    Default True.
watch_config : bool
    If True, start a daemon thread that polls the loaded config file
    every 2 seconds and reloads it when the mtime changes.  Useful
    during development to adjust log levels without restarting the
    application.  Default False. (FS-09)

Notes
-----
Calling init() more than once is a no-op.

Definition at line 1466 of file unified_debug.py.

◆ instrumentation_active()

bool oc_diagnostics.unified_debug.instrumentation_active ( )

Definition at line 954 of file unified_debug.py.

◆ instrumentation_allow_all()

bool oc_diagnostics.unified_debug.instrumentation_allow_all ( )

Return True when all components should be instrumented regardless of type. (FS-13)

Definition at line 968 of file unified_debug.py.

◆ instrumentation_allow_custom_components()

bool oc_diagnostics.unified_debug.instrumentation_allow_custom_components ( )

Definition at line 964 of file unified_debug.py.

◆ instrumentation_verbose()

bool oc_diagnostics.unified_debug.instrumentation_verbose ( )

Definition at line 960 of file unified_debug.py.

◆ set_debug_level()

None oc_diagnostics.unified_debug.set_debug_level	(	str	domain,
		int	level )

Set the debug level for a domain at runtime (0–9).

Updates ``DEBUG_LEVELS`` immediately; takes effect on the next ``_dbg()``
call.  Emits a ``UserWarning`` and returns without modifying anything if
``level`` is not an integer in 0–9.

Definition at line 977 of file unified_debug.py.

◆ set_global_setting()

None oc_diagnostics.unified_debug.set_global_setting	(	str	key,
			value )

Update a global diagnostic setting at runtime.

Valid keys: ``silent_mode``, ``enable_timestamps``, ``enable_colors``,
``include_filename``, ``output_mode``.  Emits a ``UserWarning`` for
unknown keys and returns without modifying anything.

Definition at line 995 of file unified_debug.py.

Variable Documentation

◆ _ANSI_ESCAPE_RE

oc_diagnostics.unified_debug._ANSI_ESCAPE_RE

protected

Initial value:

=  re.compile(
    r'\033(?:\‍[[^A-Za-z]*[A-Za-z]|\‍][^\007\033]*(?:\007|\033\\)|.)'
)

Definition at line 556 of file unified_debug.py.

◆ _COLOR_NAME_MAP

dict oc_diagnostics.unified_debug._COLOR_NAME_MAP

protected

Initial value:

=  {
    "red":     "\033[91m",
    "green":   "\033[92m",
    "yellow":  "\033[93m",
    "blue":    "\033[94m",
    "magenta": "\033[95m",
    "cyan":    "\033[96m",
    "white":   "\033[97m",
    "gray":    "\033[90m",
    "default": "\033[0m",
}

Definition at line 106 of file unified_debug.py.

◆ _colors

oc_diagnostics.unified_debug._colors

protected

Definition at line 395 of file unified_debug.py.

◆ _config_log_file_path

oc_diagnostics.unified_debug._config_log_file_path = _settings.get("log_file_path")

protected

Definition at line 521 of file unified_debug.py.

◆ _CONFIG_MTIME

float oc_diagnostics.unified_debug._CONFIG_MTIME = 0.0

protected

Definition at line 153 of file unified_debug.py.

◆ _CONFIG_PATH

str oc_diagnostics.unified_debug._CONFIG_PATH = ""

protected

Definition at line 152 of file unified_debug.py.

◆ _CONFIG_SCHEMA

dict oc_diagnostics.unified_debug._CONFIG_SCHEMA

protected

Initial value:

=  {
    "type": "object",
    "properties": {
        # V2.0 spec key
        "DEBUG_LEVELS": _DOMAIN_SCHEMA,
        # Legacy key (backwards compat)
        "domains": _DOMAIN_SCHEMA,
        "global_settings": {"type": "object"},
    },
}

Definition at line 140 of file unified_debug.py.

◆ _config_source

oc_diagnostics.unified_debug._config_source

protected

Definition at line 395 of file unified_debug.py.

◆ _DEFAULT_UI_EVENT_PROPERTIES

tuple oc_diagnostics.unified_debug._DEFAULT_UI_EVENT_PROPERTIES

protected

Initial value:

=  (
    "n_clicks", "value", "data", "figure", "selectedData"
)

Definition at line 434 of file unified_debug.py.

◆ _DOMAIN_SCHEMA

dict oc_diagnostics.unified_debug._DOMAIN_SCHEMA

protected

Initial value:

=  {
    "type": "object",
    "additionalProperties": {
        "oneOf": [
            {"type": "integer", "minimum": 0, "maximum": 9},
            {
                "type": "object",
                "properties": {
                    "level": {"type": "integer", "minimum": 0, "maximum": 9},
                    "color": {"type": "string"},
                },
                "required": ["level"],
            },
        ]
    },
}

Definition at line 123 of file unified_debug.py.

◆ _env_level

oc_diagnostics.unified_debug._env_level = os.environ.get("OC_DIAGNOSTICS_LEVEL", "").strip()

protected

Definition at line 465 of file unified_debug.py.

◆ _env_level_int

oc_diagnostics.unified_debug._env_level_int = int(_env_level)

protected

Definition at line 467 of file unified_debug.py.

◆ _env_log_file

str oc_diagnostics.unified_debug._env_log_file = _safe_env_path("OC_DIAGNOSTICS_LOG_FILE")

protected

Definition at line 520 of file unified_debug.py.

◆ _GIT_URL_RE

re oc_diagnostics.unified_debug._GIT_URL_RE

protected

Initial value:

=  re.compile(
    r"(?P<scheme>https?://)[^/@\s]+@",
)

Definition at line 493 of file unified_debug.py.

◆ _header_written

bool oc_diagnostics.unified_debug._header_written = False

protected

Definition at line 531 of file unified_debug.py.

◆ _init_warned

bool oc_diagnostics.unified_debug._init_warned = False

protected

Definition at line 1462 of file unified_debug.py.

◆ _initialized

bool oc_diagnostics.unified_debug._initialized = False

protected

Definition at line 1461 of file unified_debug.py.

◆ _interceptor_active

oc_diagnostics.unified_debug._interceptor_active = threading.local()

protected

Definition at line 1273 of file unified_debug.py.

◆ _io_fallback_warned

bool oc_diagnostics.unified_debug._io_fallback_warned = False

protected

Definition at line 1463 of file unified_debug.py.

◆ _KV_SECRET_RE

re oc_diagnostics.unified_debug._KV_SECRET_RE

protected

Initial value:

=  re.compile(
    r"(?i)\b(?P<key>token|secret|api[_-]?key|password|passwd|"
    r"auth[_-]?token|access[_-]?token|bearer)\s*[=:]\s*"
    r"(?:\"[^\"]*\"|'[^']*'|\S+)",
)

Definition at line 505 of file unified_debug.py.

◆ _levels

oc_diagnostics.unified_debug._levels

protected

Definition at line 395 of file unified_debug.py.

◆ _log_lock

oc_diagnostics.unified_debug._log_lock = threading.Lock()

protected

Definition at line 532 of file unified_debug.py.

◆ _MAX_CONFIG_BYTES

int oc_diagnostics.unified_debug._MAX_CONFIG_BYTES = 10 * 1024 * 1024

protected

Definition at line 164 of file unified_debug.py.

◆ _MAX_ENV_PATH_LEN

int oc_diagnostics.unified_debug._MAX_ENV_PATH_LEN = 4096

protected

Definition at line 163 of file unified_debug.py.

◆ _original_excepthook

oc_diagnostics.unified_debug._original_excepthook = None

protected

Definition at line 1228 of file unified_debug.py.

◆ _prod_downgrade_warned

set oc_diagnostics.unified_debug._prod_downgrade_warned = set()

protected

Definition at line 457 of file unified_debug.py.

◆ _settings

oc_diagnostics.unified_debug._settings

protected

Definition at line 395 of file unified_debug.py.

◆ _TOKEN_PREFIXES_RE

re oc_diagnostics.unified_debug._TOKEN_PREFIXES_RE

protected

Initial value:

=  re.compile(
    r"\b(?P<prefix>ghp_|gho_|ghu_|ghs_|ghr_|sk-|xoxb-|xoxp-|eyJ)[A-Za-z0-9_\-\.]{10,}",
)

Definition at line 499 of file unified_debug.py.

◆ ADDITIONAL_STRUCTURAL_EXACT

frozenset oc_diagnostics.unified_debug.ADDITIONAL_STRUCTURAL_EXACT

Initial value:

=  frozenset(
    _settings.get("structural_id_exact", [])
)

Definition at line 409 of file unified_debug.py.

◆ ADDITIONAL_STRUCTURAL_PREFIXES

tuple oc_diagnostics.unified_debug.ADDITIONAL_STRUCTURAL_PREFIXES

Initial value:

=  tuple(
    _settings.get("structural_id_prefixes", [])
)

Definition at line 406 of file unified_debug.py.

◆ AI_TRACE_ENABLED

bool oc_diagnostics.unified_debug.AI_TRACE_ENABLED = bool(_settings.get("ai_trace_level", False))

Definition at line 462 of file unified_debug.py.

◆ COLOR_CODES

oc_diagnostics.unified_debug.COLOR_CODES = _colors

Definition at line 398 of file unified_debug.py.

◆ CONFIG_SOURCE

oc_diagnostics.unified_debug.CONFIG_SOURCE = _config_source

Definition at line 400 of file unified_debug.py.

◆ DEBUG_LEVELS

oc_diagnostics.unified_debug.DEBUG_LEVELS = _levels

Definition at line 397 of file unified_debug.py.

◆ ENABLE_COLORS

oc_diagnostics.unified_debug.ENABLE_COLORS = _settings["enable_colors"]

Definition at line 413 of file unified_debug.py.

◆ ENABLE_TIMESTAMPS

oc_diagnostics.unified_debug.ENABLE_TIMESTAMPS = _settings["enable_timestamps"]

Definition at line 412 of file unified_debug.py.

◆ HTTP_REDACT_HEADERS

frozenset oc_diagnostics.unified_debug.HTTP_REDACT_HEADERS

Initial value:

=  frozenset(
    h.lower() for h in _settings.get("http_redact_headers",
    ["authorization", "cookie", "set-cookie", "x-api-key"])
)

Definition at line 425 of file unified_debug.py.

◆ INCLUDE_FILENAME

oc_diagnostics.unified_debug.INCLUDE_FILENAME = _settings["include_filename"]

Definition at line 414 of file unified_debug.py.

◆ INSTRUMENTATION_ALL

bool oc_diagnostics.unified_debug.INSTRUMENTATION_ALL = _settings.get("instrumentation_allow_all", False)

Definition at line 431 of file unified_debug.py.

◆ INSTRUMENTATION_ENABLED

oc_diagnostics.unified_debug.INSTRUMENTATION_ENABLED = _settings["instrumentation_enabled"]

Definition at line 401 of file unified_debug.py.

◆ LOG_DIR

str oc_diagnostics.unified_debug.LOG_DIR = _safe_env_path("OC_DIAGNOSTICS_LOG_DIR") or os.path.join(os.getcwd(), "logs")

Definition at line 515 of file unified_debug.py.

◆ LOG_FILE

str oc_diagnostics.unified_debug.LOG_FILE = _env_log_file or _config_log_file_path or None

Definition at line 526 of file unified_debug.py.

◆ MAX_LOG_FILES

int oc_diagnostics.unified_debug.MAX_LOG_FILES = _settings["max_log_files"]

Definition at line 418 of file unified_debug.py.

◆ MAX_LOG_SIZE_BYTES

tuple oc_diagnostics.unified_debug.MAX_LOG_SIZE_BYTES

Initial value:

=  (
    int(_settings["max_log_size_mb"] * 1024 * 1024)
    if _settings["max_log_size_mb"] > 0 else 0
)

Definition at line 419 of file unified_debug.py.

◆ ORIGINAL_STDERR

oc_diagnostics.unified_debug.ORIGINAL_STDERR = sys.stderr

Definition at line 529 of file unified_debug.py.

◆ ORIGINAL_STDOUT

oc_diagnostics.unified_debug.ORIGINAL_STDOUT = sys.stdout

Definition at line 528 of file unified_debug.py.

◆ OUTPUT_MODE

oc_diagnostics.unified_debug.OUTPUT_MODE = _settings["output_mode"]

Definition at line 415 of file unified_debug.py.

◆ PROD_MAX_LEVEL

int oc_diagnostics.unified_debug.PROD_MAX_LEVEL = int(_settings.get("prod_max_level", 2))

Definition at line 454 of file unified_debug.py.

◆ PROD_MODE

tuple oc_diagnostics.unified_debug.PROD_MODE

Initial value:

=  (
    os.environ.get("OC_DIAGNOSTICS_MODE", "").strip().lower() in ("prod", "production", "safe")
    or _settings.get("mode", "") in ("prod", "production", "safe")
)

Definition at line 443 of file unified_debug.py.

◆ REDACT_SECRETS

bool oc_diagnostics.unified_debug.REDACT_SECRETS = bool(_settings.get("redact_secrets", True))

Definition at line 488 of file unified_debug.py.

◆ REDACTION_PATTERNS

list oc_diagnostics.unified_debug.REDACTION_PATTERNS = []

Definition at line 474 of file unified_debug.py.

◆ SILENT_MODE

oc_diagnostics.unified_debug.SILENT_MODE = _settings["silent_mode"]

Definition at line 402 of file unified_debug.py.

◆ UI_EVENT_PROPERTIES

tuple oc_diagnostics.unified_debug.UI_EVENT_PROPERTIES

Initial value:

=  tuple(
    _settings.get("ui_event_properties") or _DEFAULT_UI_EVENT_PROPERTIES
)

Definition at line 437 of file unified_debug.py.

Classes

Functions

Variables

Detailed Description

Function Documentation

◆ _adbg()

◆ _apply_redaction()

◆ _dbg()

◆ _dbg_ai_trace()

◆ _dbg_assert()

◆ _emit()

◆ _ensure_log_dir_and_header()

◆ _exception_hook()

◆ _get_color()

◆ _get_log_file()

◆ _get_timestamp()

◆ _load_debug_config()

◆ _prune_old_log_files()

◆ _reload_config()

◆ _reset_color()

◆ _safe_env_path()

◆ _watch_config_loop()

◆ _write_to_file()

◆ dbg_metrics()

◆ dbg_profile()

◆ dbg_scope()

◆ dbg_timed()

◆ dbg_trace()

◆ init()

◆ instrumentation_active()

◆ instrumentation_allow_all()

◆ instrumentation_allow_custom_components()

◆ instrumentation_verbose()

◆ set_debug_level()

◆ set_global_setting()

Variable Documentation

◆ _ANSI_ESCAPE_RE

◆ _COLOR_NAME_MAP

◆ _colors

◆ _config_log_file_path

◆ _CONFIG_MTIME

◆ _CONFIG_PATH

◆ _CONFIG_SCHEMA

◆ _config_source

◆ _DEFAULT_UI_EVENT_PROPERTIES

◆ _DOMAIN_SCHEMA

◆ _env_level

◆ _env_level_int

◆ _env_log_file

◆ _GIT_URL_RE

◆ _header_written

◆ _init_warned

◆ _initialized

◆ _interceptor_active

◆ _io_fallback_warned

◆ _KV_SECRET_RE

◆ _levels

◆ _log_lock

◆ _MAX_CONFIG_BYTES

◆ _MAX_ENV_PATH_LEN

◆ _original_excepthook

◆ _prod_downgrade_warned

◆ _settings

◆ _TOKEN_PREFIXES_RE

◆ ADDITIONAL_STRUCTURAL_EXACT

◆ ADDITIONAL_STRUCTURAL_PREFIXES

◆ AI_TRACE_ENABLED

◆ COLOR_CODES

◆ CONFIG_SOURCE

◆ DEBUG_LEVELS

◆ ENABLE_COLORS

◆ ENABLE_TIMESTAMPS

◆ HTTP_REDACT_HEADERS

◆ INCLUDE_FILENAME

◆ INSTRUMENTATION_ALL

◆ INSTRUMENTATION_ENABLED

◆ LOG_DIR

◆ LOG_FILE

◆ MAX_LOG_FILES

◆ MAX_LOG_SIZE_BYTES