spacr.flowview.trace¶

Low-cost, failure-isolated instrumentation for FlowView stages.

Functions¶

`disable`(→ None)	Disable tracing globally.
`enable`(→ spacr.flowview.collector.Collector)	Enable tracing globally and optionally install a run collector.
`get_collector`(→ spacr.flowview.collector.Collector)	Return the process-wide collector used by new trace events.
`is_enabled`(→ bool)	Return the process-wide tracing state.
`stage`(, produces, params, Any] \| None = None, node_id)	Describe one stage for use as a decorator or context manager.

Module Contents¶

spacr.flowview.trace.disable() → None[source]¶: Disable tracing globally.

spacr.flowview.trace.enable(collector: spacr.flowview.collector.Collector | None = None) → spacr.flowview.collector.Collector[source]¶: Enable tracing globally and optionally install a run collector.

spacr.flowview.trace.get_collector() → spacr.flowview.collector.Collector[source]¶: Return the process-wide collector used by new trace events.

spacr.flowview.trace.is_enabled() → bool[source]¶: Return the process-wide tracing state.

spacr.flowview.trace.stage(label: str, *, kind: spacr.flowview.model.NodeKind | str = NodeKind.PROCESS, consumes: Iterable[str] = (), produces: Iterable[str] = (), params: Mapping[str, Any] | None = None, node_id: str | None = None) → _StageSpec | _NullStage[source]¶

Describe one stage for use as a decorator or context manager.

Parameters:

label – Human-readable stage label used in trace events.
kind – Input, process, or output role of the stage node.
consumes – Labels of input artifacts consumed by the stage.
produces – Labels of output artifacts produced by the stage.
params – Optional stage metadata to retain in the trace graph.
node_id – Optional stable node identifier. One is derived from label when this is omitted.

Returns:

Active stage specification, or a no-op stage while tracing is disabled.

Nested helpers¶

_StageSpec.__call__.traced(*args: Any, **kwargs: Any) → Any¶

Call the captured function with optional stage tracing.

Parameters:

args – positional arguments forwarded unchanged.
kwargs – keyword arguments forwarded unchanged.

Returns:

the captured function’s result. Enablement is rechecked at invocation time; enabled calls run inside a fresh stage runtime, which records completion or failure while preserving the original exception.

spacr/flowview/trace.py:256