Skip to main content

Execution Management

Execution management in this SDK is centered around the Run class, which provides a high-level interface for interacting with remote task and workflow executions. Located in src/flyte/remote/_run.py, the Run class acts as a controller for an execution, allowing you to monitor its progress, retrieve results, and manage its lifecycle.

The Run Lifecycle​

A Run object represents an execution on the remote Union API. It wraps an underlying Action and provides methods to synchronize the local state with the remote server.

Obtaining a Run Reference​

You typically obtain a Run object in one of two ways:

  1. Starting a new execution: Using flyte.run(), which triggers a remote execution and returns a Run instance.
  2. Fetching an existing execution: Using the Run.get(name) class method to retrieve a run by its unique name.
from flyte.remote import Run

# Fetch an existing run by name
run = Run.get("my-execution-name")

print(f"Run URL: {run.url}")

Tracking Status​

The state of a run is exposed through the phase and raw_phase properties. The SDK uses the ActionPhase model to represent these states.

  • run.phase: Returns a string representation of the current phase (e.g., "SUCCEEDED", "RUNNING", "FAILED").
  • run.raw_phase: Returns the underlying phase_pb2.ActionPhase enum value.
  • run.done(): A convenience method that returns True if the run has reached a terminal state.

Monitoring Executions​

The SDK provides both blocking and streaming mechanisms to monitor execution progress.

Waiting for Completion​

The wait() method is the primary way to block execution until a run finishes. It is decorated with @syncify, meaning it can be called synchronously in standard scripts or asynchronously using await run.wait.aio() in async contexts.

When called in an interactive environment, wait() displays a rich progress panel showing status transitions and time elapsed.

# Blocks until the run reaches a terminal state (SUCCEEDED, FAILED, etc.)
run.wait()

if run.phase == "SUCCEEDED":
    print("Execution finished successfully!")

Real-time Monitoring​

For more granular control, the watch() method returns an async generator that yields ActionDetails every time the run's state changes. This is useful for building custom dashboards or logging systems.

async def monitor_run(run: Run):
    async for details in run.watch():
        print(f"Current Phase: {details.phase}")

Retrieving Results and Metadata​

Once a run is complete (or even while it is running, for inputs), you can access its data and configuration.

Inputs and Outputs​

The inputs() and outputs() methods provide access to the data passed to and returned by the execution. These methods are asynchronous but can be called synchronously thanks to the SDK's syncification layer.

# Retrieve outputs after completion
results = run.outputs()
print(f"Result: {results}")

Run Details​

While the Run class focuses on execution control, the RunDetails class (also in src/flyte/remote/_run.py) provides access to the execution's configuration and metadata, such as:

  • Labels and Annotations
  • Environment Variables
  • Interruptibility status
  • Cache overwrite settings

You can access these details via the run.details() method:

details = run.details()
print(f"Labels: {details.pb2.run_spec.labels}")
print(f"Is Interruptible: {details.pb2.run_spec.interruptible}")

Management Operations​

Listing Runs​

The Run.listall() method allows you to query historical executions. It supports extensive filtering by phase, task name, version, and creation time.

from flyte.models import ActionPhase

# List the 5 most recent successful runs for a specific task
recent_runs = Run.listall(
    task_name="my_project.tasks.my_task",
    in_phase=(ActionPhase.SUCCEEDED,),
    sort_by=("created_at", "desc"),
    limit=5
)

for r in recent_runs:
    print(f"Found run: {r.name} created at {r.pb2.action.metadata.created_at}")

Aborting Executions​

If a run needs to be terminated prematurely, the abort() method sends a termination request to the server. The SDK handles cases where the run might have already finished (e.g., NOT_FOUND errors) gracefully.

# Abort a running execution with a reason
run.abort(reason="Parameters were incorrect, restarting.")

Logs and Debugging​

The Run class provides programmatic access to execution logs through get_logs() and show_logs().

  • show_logs(): Fetches and prints logs to the console, with options for filtering system logs and showing timestamps.
  • get_logs(): Returns an iterator (or async iterator) of log lines for programmatic processing.
  • get_debug_url(): For tasks configured with debugging enabled, this method retrieves the VS Code Debugger URL once it becomes available.
# Stream logs to the console
run.show_logs(max_lines=50, show_ts=True)