bloc.reporting.debug_trace#

Phase-level debug tracing for long-running calculation-note generation.

Enabled by RUNNER_DEBUG=1 – which GitHub Actions sets automatically whenever a job is re-run with “Enable debug logging” – or by BLOC_DEBUG for local use. Disabled (and effectively free) otherwise.

Motivation: models-tests shard jobs have been killed by runner memory starvation inside calculation-note collection, leaving a CI log whose last line gives no indication of which phase was in flight or how much memory had accumulated (see issue #326). Each trace() call emits the phase, the time since the previous trace, and the current resident-set size, so a post-mortem can attribute the death to a specific phase.

Functions#

debug_enabled()

Return True when phase tracing should be emitted.

rss_gb()

Best-effort resident-set size of this process in GB (None if unknown).

trace(label[, scope])

Print label with elapsed-since-previous-trace and current RSS.

Module Contents#

bloc.reporting.debug_trace.debug_enabled()#

Return True when phase tracing should be emitted.

bloc.reporting.debug_trace.rss_gb()#

Best-effort resident-set size of this process in GB (None if unknown).

bloc.reporting.debug_trace.trace(label, scope='')#

Print label with elapsed-since-previous-trace and current RSS.

Parameters:

  • label (str) – Phase description, e.g. "node data: collect_node_properties done".

  • scope (str, optional) – Context prefix, typically the scenario id.

Notes

dt is the wall time since the previous trace() call in this process (any scope), which is what makes a slow phase stand out. It is omitted on the first call.