Debugging¶
The debugging helpers are meant for external scripts and small home-brewed
workflow code. Diagnostics provides an opt-in pattern for writing artifacts
such as plots, reports, or intermediate snapshots without adding global debug
flags or commented-out debugging blocks.
When diagnostics are disabled, hooks return immediately and do not create output directories:
from snippets.debugging import Diagnostics, NO_DIAGNOSTICS
def write_report(value, path):
path.write_text(f"value={value}\n", encoding="utf-8")
def process_value(value, diagnostics=NO_DIAGNOSTICS):
diagnostics.emit(
"input",
lambda path: write_report(value, path / "input.txt"),
)
result = value * 2
diagnostics.emit(
"output",
lambda path: write_report(result, path / "output.txt"),
)
return result
diagnostics = Diagnostics(enabled=True, outdir="debug", only={"output"})
process_value(3, diagnostics=diagnostics)
Use child() to keep event names explicit in nested workflows:
diagnostics = Diagnostics(
enabled=True,
outdir="debug",
only={"preprocess.input"},
)
preprocess_diagnostics = diagnostics.child("preprocess")
preprocess_diagnostics.emit("input", lambda path: write_report(3, path / "input.txt"))
This writes to debug/preprocess/input/input.txt. Because child diagnostics use
qualified event names, the only filter must use preprocess.input, not
input.
Optional dependency fallback¶
If a workflow can run without snippets, define a small fallback and skip
optional setup when Diagnostics is unavailable:
try:
from snippets.debugging import NO_DIAGNOSTICS, Diagnostics
except ImportError:
class NoDiagnostics:
enabled = False
def active(self, name):
return False
def emit(self, name, fn):
return None
def child(self, prefix):
return self
NO_DIAGNOSTICS = NoDiagnostics()
Diagnostics = None
diagnostics = NO_DIAGNOSTICS
if Diagnostics is not None:
diagnostics = Diagnostics(enabled=True, outdir="debug")
Functions can still default to NO_DIAGNOSTICS, so callers that do not need
artifacts do not need any setup.
Performance¶
Diagnostic hooks belong at stage boundaries. Do not put emit() calls inside
tight numerical loops, per-cell loops, Dask block kernels, numba or JAX compiled
sections, or xarray apply_ufunc inner functions.
In hot paths, check diagnostics.active(name) before doing any setup for a
diagnostic artifact.