Skip to content
Factflow

Monitor and replay

You have an execution that completed. Now you'll inspect the output, trace messages end-to-end, and replay a stage without re-fetching source data.

Prerequisites

Section titled “Prerequisites”

Inspect storage

Section titled “Inspect storage”

List every object produced by this execution:

Terminal window
factflow storage list --prefix executions/$EXEC_ID/

Read one (prints to stdout):

Terminal window
factflow storage get "executions/b3a1.../sitemap_scraper/web_scraper/msg-042"

Inspect just the sidecar metadata (who wrote it, when, with what config hash):

Terminal window
factflow storage metadata "executions/b3a1.../sitemap_scraper/web_scraper/msg-042"

Stream writes as they happen (during a live execution):

Terminal window
factflow storage watch $EXEC_ID

Trace lineage

Section titled “Trace lineage”

Lineage records one row per message per adapter invocation. List everything for the execution:

Terminal window
factflow lineage list --execution-id $EXEC_ID

Drill into a message's full chain (all ancestors and descendants):

Terminal window
factflow lineage chain MSG_ID

Just the children (messages this one produced):

Terminal window
factflow lineage children MSG_ID

List failures across the execution:

Terminal window
factflow lineage failures --execution-id $EXEC_ID

Replay from storage

Section titled “Replay from storage”

Replay re-publishes a stored artefact back into the pipeline, letting you rerun a downstream stage without refetching source data. Useful when:

  • An adapter had a bug; you fixed it; re-run against the same input
  • A later stage timed out; rerun it
  • You want to test an updated config against the same data

factflow execution replay always needs --from-stage (where to read the stored artefact) and --to-route (which route to publish it into). Both are required.

Replay within the same pipeline (target a route of the parent's own config):

Terminal window
factflow execution replay $EXEC_ID \
  --from-stage web_scraper \
  --to-route markdown_processor

Cross-pipeline replay (publish into a route of a different config, creating a new execution):

Terminal window
factflow execution replay $EXEC_ID \
  --from-stage web_scraper \
  --to-route markdown_processor \
  --config-id markdown-pipeline

Replay requires the data to still exist

Section titled “Replay requires the data to still exist”

Replay reads executions/SRC/ROUTE/STAGE/* from storage. If objects are missing, replay fails — storage is not a cache. Storage retention is a deployment concern.

Useful sidecar commands

Section titled “Useful sidecar commands”
Terminal window
factflow system health --debug      # verify every subsystem is live
factflow system metrics             # aggregate orchestrator state
factflow pipeline list              # every running route, across all executions
factflow pipeline pause ROUTE_ID    # pause one route globally (drains in flight)
factflow pipeline resume ROUTE_ID

What's next

Section titled “What's next”