Skip to content

Tracing

TraceEvent dataclass

A single recorded execution attempt for a node.

Captures the node_id, run_id, 1-based attempt number, timestamp_utc, input_state, and output_state (or None on failure). On failure, failure holds the FailureClass and failure_message provides a human-readable description.

step_id property

Alias for node_id — paradigm-neutral name for the execution step.

ExecutionTrace

Ordered collection of TraceEvent instances for a pipeline run.

Provides filtering, diffing, serialization, and iteration over events.

Example

result = await runner.run(nodes, state)

# Inspect failures
for event in result.trace.failures():
    print(f"{event.node_id}: {event.failure_message}")

# Compare two traces
diffs = trace_a.diff(trace_b)

# Export to JSON
json_str = result.trace.to_json()

append(event)

Append a trace event.

events_for(node_id)

Return all events for the given node.

failures()

Return all events that represent failures.

to_json()

Serialize all events to a JSON string.

diff(other)

Compare this trace against other, ignoring timestamps and durations.

Returns a list of human-readable difference descriptions. An empty list means the traces are logically equivalent.

replay()

Yield events in the order they were recorded.

RunStatus

Bases: StrEnum

Terminal status of a pipeline run.

  • COMPLETED: All nodes executed successfully.
  • FAILED: A terminal failure stopped the pipeline.
  • PARTIAL: Retries were exhausted on a recoverable/ambiguous failure.
  • RESUMED: The pipeline completed after resuming from a checkpoint.

ExecutionResult dataclass

Final output of a pipeline run.

Contains the run_id, terminal status, final_state (the last valid state produced, or the initial state on early failure), the complete trace with all attempts, and aggregate total_cost_usd / total_tokens across all nodes.