Python: What is the recommended way to show the path a workflow run took, for past and paused runs?

[Banka Uday (banka-uday-4129)]

Python: What is the recommended way to show the path a workflow run took, for past and paused runs?

What we're trying to do

We draw our workflows as a graph (one node per executor) and want to show, for a given run, the path it actually took:

• which executors ran, and how many times (loops);
• which edges were taken: a normal edge, which case of a switch-case edge group, and all the sources of a fan-in;
• each executor's state in that run: running, completed, failed, or waiting for a human response (ctx.request_info).

We need this in two situations:

1. Past runs: a user opens a run that finished minutes or days ago and sees the path it took.
2. Paused runs: a run is waiting on one or more request_info requests, possibly on two parallel branches at once. Someone opens it and should see where it is waiting. Later it is resumed from a checkpoint, possibly in another process, and the view continues from there.

Runs are started both with workflow.run(..., stream=True) and with stream=False.

What makes it hard

• Workflow events are live only and not persisted. After a run, or after a checkpoint restore in a new process, the events of earlier supersteps are gone.
• executor_invoked / executor_completed don't say where the message came from. The edge taken has to be inferred from the graph, which is ambiguous when an executor has several incoming edges, and for fan-in.
• An executor that called ctx.request_info is still reported executor_completed when its handler returns, although it is waiting for an answer. Whether it is "done" or "waiting" isn't visible from that event.
• A request and its response are two separate handler calls, often in different run() calls, so linking "this executor asked" with "this executor resumed on the answer" isn't obvious from events.
• On resume from a checkpoint, still-pending request_info events are emitted again.
• With stream=False, events are only available after run() returns.
• Checkpoints hold the latest state, not a history of which executors ran or which edges were taken.
• OTel spans (executor.process, message.send, edge group spans, span links) seem to contain the path. However, they are exported asynchronously, are absent when tracing is disabled, and don't express "waiting for a human".

Questions

1. What is the recommended way to record and later show the path a workflow run took, including the edges taken and executors waiting on request_info? Is there an existing or planned API for a persisted execution history?
2. Should we persist the workflow events and replay them to rebuild the path? If so:
   • Which events are enough?
   • How should the request_info events re-emitted after a checkpoint restore be handled?
   • How should runs with stream=False be handled?
3. Or should we use the OpenTelemetry data (spans and span links)? If so:
   • Which spans and attributes identify the edge taken and the source executor(s)?
   • How do we tell from the spans that an executor is waiting on a request?
   • Is the span structure considered stable?
4. Or is there another approach you'd recommend, for example recording each executor run ourselves from inside the handler, or something built on checkpoints?

Thanks!

[yuzhou (ZYZ666-RGB)]

There isn't an official, persistable "path this run took" API today. A checkpoint stores the latest workflow state (messages, executor state, iteration, and pending_request_info_events), not a history of which edges fired.

The robust approach is to persist the event stream yourself:

• if you run with stream=True, record events as they arrive
• if you use run(..., stream=False) (the default), the returned WorkflowRunResult includes the event list — persist that after the run returns
• if you need status events in the non-streaming path, pass include_status_events=True

Events that are useful for a run timeline include executor_invoked, executor_completed, executor_failed, request_info (with source_executor_id and request_id), and status events such as IDLE_WITH_PENDING_REQUESTS.

A few caveats that matter for paused or restored runs:

• After restoring from a checkpoint, pending request_info events may be emitted again. Dedupe by request_id, and treat a re-emitted event as still waiting — not as a new request. If a response was already provided, that request is not re-emitted.
• executor_completed after a handler calls request_info only means that handler returned. It does not mean the requested work is finished.
• Edges — especially multi-in, fan-in, and switch-case — often cannot be uniquely inferred from events, so I would not treat event logs as a perfect path reconstruction.

DevUI's get_session_history is an in-process session request log, not a persistable path graph. OpenTelemetry traces can add useful telemetry, but they are not enough on their own: they do not express "waiting for a human" the way request_info does, and I would not treat their span shape as a stable API for this.