View history of execution steps

You can retrieve the history of a specified workflow execution as a list of step entries. Each step entry provides information that can assist you when analyzing, debugging, or optimizing a workflow. For example, you can confirm which steps actually executed, and you can determine the duration and success of a step. This can be particularly helpful when debugging a large or complicated non-linear workflow (one with many parallel branches, for example).

A step entry represents either an actual step in the source code (for example, assign or call) or an instruction block (for example, a for loop or a try/retry/except block). For a complete list of step types, see StepType.

How to retrieve step entries

You can retrieve step entries either by sending a request to the Workflow Executions REST API or through the Google Cloud console:

  • Google Cloud console—in this document, see View step entries in the console.

    In addition to listing the step entries and their details, the console provides a graphical representation of the execution steps, making it easier to view and analyze the path of a workflow execution.

  • Workflow Executions REST API—in this document, see Retrieve a step entry and List step entries.

Step entry information

A step entry includes the following information. For more details, in this document, see the Examples.

Name Full resource name of the step entry which is a unique ID with the following format, and where STEPENTRY_ID is an increasing counter:
projects/PROJECT_NUMBER/locations/LOCATION/workflows/WORKFLOW_ID/executions/EXECUTION_ID/stepEntries/STEPENTRY_ID
For example:
projects/123456789012/locations/us-central1/workflows/myFirstWorkflow/executions/ae8a66a1-cefa-4d16-8a2f-d50c712d8ef1/stepEntries/2
Create and update times Timestamps for the creation time of the step entry and its most recent update. If a step entry has completed, updateTime indicates the completion time.
Routine and step names Names of the routine and step that the step entry belongs to. A routine name is the subworkflow name defined in the YAML or JSON source code. The top level routine name is main.
State and progress type State of the step entry—for example, if the entry has succeeded or failed, or if a step entry is in progress and the type of progress. For a complete list of states and progress types, see State and ProgressType.
Navigation information Position of the step entry so that you can better understand the hierarchy and flow of the workflow—for example, what step entries come before or after the current step entry, or which are parents or children of the step entry. For details, see NavigationInfo.
Metadata Data related to an iterative step entry including an ID that indicates the child thread (for example, which STEP_PARALLEL_BRANCH_ENTRY in STEP_PARALLEL_BRANCH) or the iteration of a for loop (for example, which STEP_FOR_ITERATION in STEP_FOR). For details, see StepEntryMetadata.
Exceptions Payload related to any exceptions and that provides a description of why a step entry has failed.

View step entries in the console

You can view the step entries for a specific workflow execution in the Google Cloud console.

  1. In the Google Cloud console, go to the Workflows page.

    Go to Workflows

  2. Click the name of the workflow to go to its Workflow details page.

  3. For details about a particular execution, click its execution ID.

    On the Summary tab, information about the overall execution is provided, including any exception that led to the failure of the execution. For more information, see Execution error messages.

  4. To view the workflow execution history as a list of step entries, click the Steps tab.

    All step entries for the workflow execution are listed.

  5. To filter the step entries, use the Filter field at the top of the table to select a property and a value—for example, State: Failed.

  6. To display links for any Parent, Children, Next, and Previous step entries, click a specific step entry.

    If you click a link, the other links automatically update. For example, Parent will link to the parent of the step entry that you clicked.

  7. The Visualization panel provides a graphical representation of the steps in the workflow and helps you understand the workflow path.

    Visualization panel example

    Click diagram to enlarge it:

    Visualization panel displaying workflow with failed steps

    Note that the visualization can differ from the step entries. For example, a for block is depicted as a single component in the visualization; however, depending on the number of iterations, there can be multiple step entries.

    You can do the following in the panel:

    • Zoom in or out of the visualization
    • Collapse or expand parent step entries
    • Click a step entry and view its previous and next entries
    • Confirm successful and failed step entries as indicated by a green checkmark or red exclamation mark
    • Close the Visualization panel by clicking the expander arrow; click it again to open the panel

Before you retrieve a step entry

To get the permissions that you need to retrieve a step entry, ask your administrator to grant you the Workflows Admin (workflows.stepEntries.get) IAM role on your project. For more information about granting roles, see Manage access to projects, folders, and organizations.

You might also be able to get the required permissions through custom roles or other predefined roles.

Retrieve a step entry

To retrieve a step entry for a given workflow execution, use the projects.locations.workflows.executions.stepEntries.get method.

Before using any of the request data, make the following replacements:

  • PROJECT_NUMBER: your Google Cloud project number listed in the IAM & Admin Settings page.
  • LOCATION: the region in which the workflow is deployed—for example, us-central1.
  • WORKFLOW_ID: the user-defined name for the workflow—for example, myFirstWorkflow.
  • EXECUTION_ID: the unique ID for a workflow execution which is returned after a workflow is executed.
  • STEPENTRY_ID: the unique ID for a step entry—for example, 1.

To send your request, expand one of these options:

You should receive a JSON response similar to the following:

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION/workflows/WORKFLOW_ID/executions/EXECUTION_ID/stepEntries/STEPENTRY_ID",
  "createTime": "2023-10-19T13:49:56.522717646Z",
  "updateTime": "2023-10-19T13:49:56.525439354Z",
  "routine": "main",
  "step": "checkSearchTermInInput",
  "stepType": "STEP_CONDITION",
  "state": "STATE_SUCCEEDED",
  "entryId": "2",
  "navigationInfo": {
    "children": [
      "3"
    ],
    "parent": "1",
    "next": "3",
    "previous": "1"
  }
}

Before you list step entries

To get the permissions that you need to list step entries, ask your administrator to grant you the Workflows Admin (workflows.stepEntries.list) IAM role on your project. For more information about granting roles, see Manage access to projects, folders, and organizations.

You might also be able to get the required permissions through custom roles or other predefined roles.

List step entries

To list the step entries for a given workflow execution, use the projects.locations.workflows.executions.stepEntries.list method. By default, results are returned in ascending order of the createTime of the step entries.

Before using any of the request data, make the following replacements:

  • PROJECT_NUMBER: your Google Cloud project number listed in the IAM & Admin Settings page.
  • LOCATION: the region in which the workflow is deployed—for example, us-central1.
  • WORKFLOW_ID: the user-defined name for the workflow—for example, myFirstWorkflow.
  • EXECUTION_ID: the unique ID for a workflow execution which is returned after a workflow is executed.

To send your request, expand one of these options:

You should receive a JSON response similar to the following:

{
  "stepEntries": [
    {
      "name": "projects/PROJECT_NUMBER/locations/LOCATION/workflows/WORKFLOW_ID/executions/EXECUTION_ID/stepEntries/1",
      "createTime": "2023-10-19T13:49:56.522705770Z",
      "updateTime": "2023-10-19T13:49:56.525439429Z",
      "routine": "main",
      "step": "checkSearchTermInInput",
      "stepType": "STEP_SWITCH",
      "state": "STATE_SUCCEEDED",
      "entryId": "1",
      "navigationInfo": {
        "children": [
          "2"
        ],
        "next": "2"
      }
    },
    {
      "name": "projects/PROJECT_NUMBER/locations/LOCATION/workflows/WORKFLOW_ID/executions/EXECUTION_ID/stepEntries/2",
      "createTime": "2023-10-19T13:49:56.522717646Z",
      "updateTime": "2023-10-19T13:49:56.525439354Z",
      "routine": "main",
      "step": "checkSearchTermInInput",
      "stepType": "STEP_CONDITION",
      "state": "STATE_SUCCEEDED",
      "entryId": "2",
      "navigationInfo": {
        "children": [
          "3"
        ],
        "parent": "1",
        "next": "3",
        "previous": "1"
      }
    },
    {
      "name": "projects/PROJECT_NUMBER/locations/LOCATION/workflows/WORKFLOW_ID/executions/EXECUTION_ID/stepEntries/3",
      "createTime": "2023-10-19T13:49:56.525379814Z",
      "updateTime": "2023-10-19T13:49:56.525439285Z",
      "routine": "main",
      "step": "checkSearchTermInInput.condition1",
      "stepType": "STEP_ASSIGN",
      "state": "STATE_SUCCEEDED",
      "entryId": "3",
      "navigationInfo": {
        "parent": "2",
        "next": "4",
        "previous": "2"
      }
    },
    {
      "name": "projects/PROJECT_NUMBER/locations/LOCATION/workflows/WORKFLOW_ID/executions/EXECUTION_ID/stepEntries/4",
      "createTime": "2023-10-19T13:49:56.525440360Z",
      "updateTime": "2023-10-19T13:49:56.716973793Z",
      "routine": "main",
      "step": "readWikipedia",
      "stepType": "STEP_CALL",
      "state": "STATE_SUCCEEDED",
      "entryId": "4",
      "navigationInfo": {
        "next": "5",
        "previous": "3"
      }
    },
    {
      "name": "projects/PROJECT_NUMBER/locations/LOCATION/workflows/WORKFLOW_ID/executions/EXECUTION_ID/stepEntries/5",
      "createTime": "2023-10-19T13:49:56.717263008Z",
      "updateTime": "2023-10-19T13:49:56.717353199Z",
      "routine": "main",
      "step": "returnOutput",
      "stepType": "STEP_RETURN",
      "state": "STATE_SUCCEEDED",
      "entryId": "5",
      "navigationInfo": {
        "previous": "4"
      }
    }
  ],
  "totalSize": 5
}

Examples

Workflow with a for block

Workflow

YAML

- assignStep:
    assign:
      - sum: 0
- forStep:
    for:
      range: [1, 2]
      value: v
      steps:
        - sumStep:
            assign:
              - sum: ${sum + v}
- returnStep:
    return: ${sum}

JSON

[
  {
    "assignStep": {
      "assign": [
        {
          "sum": 0
        }
      ]
    }
  },
  {
    "forStep": {
      "for": {
        "range": [
          1,
          2
        ],
        "value": "v",
        "steps": [
          {
            "sumStep": {
              "assign": [
                {
                  "sum": "${sum + v}"
                }
              ]
            }
          }
        ]
      }
    }
  },
  {
    "returnStep": {
      "return": "${sum}"
    }
  }
]

Diagram

Workflow with a for block

Step entries

  {
  "stepEntries": [
    {
      "name": "projects/200478149810/locations/us-central1/workflows/ck-for-block/executions/74785b43-5b9f-4adf-bde7-a9880d0e100a/stepEntries/1",
      "createTime": "2023-10-20T17:19:37.889232683Z",
      "updateTime": "2023-10-20T17:19:37.889275457Z",
      "routine": "main",
      "step": "assignStep",
      "stepType": "STEP_ASSIGN",
      "state": "STATE_SUCCEEDED",
      "entryId": "1",
      "navigationInfo": {
        "next": "2"
      }
    },
    {
      "name": "projects/200478149810/locations/us-central1/workflows/ck-for-block/executions/74785b43-5b9f-4adf-bde7-a9880d0e100a/stepEntries/2",
      "createTime": "2023-10-20T17:19:37.889276124Z",
      "updateTime": "2023-10-20T17:19:37.889474759Z",
      "routine": "main",
      "step": "forStep",
      "stepType": "STEP_FOR",
      "state": "STATE_SUCCEEDED",
      "entryId": "2",
      "navigationInfo": {
        "children": [
          "3",
          "5"
        ],
        "next": "3",
        "previous": "1"
      }
    },
    {
      "name": "projects/200478149810/locations/us-central1/workflows/ck-for-block/executions/74785b43-5b9f-4adf-bde7-a9880d0e100a/stepEntries/3",
      "createTime": "2023-10-20T17:19:37.889313107Z",
      "updateTime": "2023-10-20T17:19:37.889382353Z",
      "routine": "main",
      "step": "forStep",
      "stepType": "STEP_FOR_ITERATION",
      "state": "STATE_SUCCEEDED",
      "entryId": "3",
      "navigationInfo": {
        "children": [
          "4"
        ],
        "parent": "2",
        "next": "4",
        "previous": "2"
      },
      "stepEntryMetadata": {
        "progressType": "PROGRESS_TYPE_FOR",
        "progressNumber": "1"
      }
    },
    {
      "name": "projects/200478149810/locations/us-central1/workflows/ck-for-block/executions/74785b43-5b9f-4adf-bde7-a9880d0e100a/stepEntries/4",
      "createTime": "2023-10-20T17:19:37.889317653Z",
      "updateTime": "2023-10-20T17:19:37.889382265Z",
      "routine": "main",
      "step": "sumStep",
      "stepType": "STEP_ASSIGN",
      "state": "STATE_SUCCEEDED",
      "entryId": "4",
      "navigationInfo": {
        "parent": "3",
        "next": "5",
        "previous": "3"
      },
      "stepEntryMetadata": {
        "progressType": "PROGRESS_TYPE_FOR",
        "progressNumber": "1"
      }
    },
    {
      "name": "projects/200478149810/locations/us-central1/workflows/ck-for-block/executions/74785b43-5b9f-4adf-bde7-a9880d0e100a/stepEntries/5",
      "createTime": "2023-10-20T17:19:37.889383134Z",
      "updateTime": "2023-10-20T17:19:37.889474707Z",
      "routine": "main",
      "step": "forStep",
      "stepType": "STEP_FOR_ITERATION",
      "state": "STATE_SUCCEEDED",
      "entryId": "5",
      "navigationInfo": {
        "children": [
          "6"
        ],
        "parent": "2",
        "next": "6",
        "previous": "4"
      },
      "stepEntryMetadata": {
        "progressType": "PROGRESS_TYPE_FOR",
        "progressNumber": "2"
      }
    },
    {
      "name": "projects/200478149810/locations/us-central1/workflows/ck-for-block/executions/74785b43-5b9f-4adf-bde7-a9880d0e100a/stepEntries/6",
      "createTime": "2023-10-20T17:19:37.889384893Z",
      "updateTime": "2023-10-20T17:19:37.889474649Z",
      "routine": "main",
      "step": "sumStep",
      "stepType": "STEP_ASSIGN",
      "state": "STATE_SUCCEEDED",
      "entryId": "6",
      "navigationInfo": {
        "parent": "5",
        "next": "7",
        "previous": "5"
      },
      "stepEntryMetadata": {
        "progressType": "PROGRESS_TYPE_FOR",
        "progressNumber": "2"
      }
    },
    {
      "name": "projects/200478149810/locations/us-central1/workflows/ck-for-block/executions/74785b43-5b9f-4adf-bde7-a9880d0e100a/stepEntries/7",
      "createTime": "2023-10-20T17:19:37.889475882Z",
      "updateTime": "2023-10-20T17:19:37.889483477Z",
      "routine": "main",
      "step": "returnStep",
      "stepType": "STEP_RETURN",
      "state": "STATE_SUCCEEDED",
      "entryId": "7",
      "navigationInfo": {
        "previous": "6"
      }
    }
  ],
  "totalSize": 7
}

Workflow with a subworkflow call

Workflow

YAML

main:
  steps:
    - callStep:
        call: square
        args:
          x: 10
        result: t
    - retStep:
        return: ${t}
square:
  params: [x]
  steps:
    - assignStep:
        assign:
          - y: ${x*x}
    - retStep:
        return: ${y}

JSON

{
  "main": {
    "steps": [
      {
        "callStep": {
          "call": "square",
          "args": {
            "x": 10
          },
          "result": "t"
        }
      },
      {
        "retStep": {
          "return": "${t}"
        }
      }
    ]
  },
  "square": {
    "params": [
      "x"
    ],
    "steps": [
      {
        "assignStep": {
          "assign": [
            {
              "y": "${x*x}"
            }
          ]
        }
      },
      {
        "retStep": {
          "return": "${y}"
        }
      }
    ]
  }
}

Diagram

Workflow with a subworkflow call

Step entries

{
  "stepEntries": [
    {
      "name": "projects/200478149810/locations/us-central1/workflows/ck-for-block/executions/69da2159-1039-4f88-8d8a-12baf398f372/stepEntries/1",
      "createTime": "2023-10-21T15:25:55.406007695Z",
      "updateTime": "2023-10-21T15:25:55.412984492Z",
      "routine": "main",
      "step": "callStep",
      "stepType": "STEP_CALL",
      "state": "STATE_SUCCEEDED",
      "entryId": "1",
      "navigationInfo": {
        "children": [
          "2",
          "3"
        ],
        "next": "2"
      }
    },
    {
      "name": "projects/200478149810/locations/us-central1/workflows/ck-for-block/executions/69da2159-1039-4f88-8d8a-12baf398f372/stepEntries/2",
      "createTime": "2023-10-21T15:25:55.412921902Z",
      "updateTime": "2023-10-21T15:25:55.412967631Z",
      "routine": "square",
      "step": "assignStep",
      "stepType": "STEP_ASSIGN",
      "state": "STATE_SUCCEEDED",
      "entryId": "2",
      "navigationInfo": {
        "parent": "1",
        "next": "3",
        "previous": "1"
      }
    },
    {
      "name": "projects/200478149810/locations/us-central1/workflows/ck-for-block/executions/69da2159-1039-4f88-8d8a-12baf398f372/stepEntries/3",
      "createTime": "2023-10-21T15:25:55.412968712Z",
      "updateTime": "2023-10-21T15:25:55.412978913Z",
      "routine": "square",
      "step": "retStep",
      "stepType": "STEP_RETURN",
      "state": "STATE_SUCCEEDED",
      "entryId": "3",
      "navigationInfo": {
        "parent": "1",
        "next": "4",
        "previous": "2"
      }
    },
    {
      "name": "projects/200478149810/locations/us-central1/workflows/ck-for-block/executions/69da2159-1039-4f88-8d8a-12baf398f372/stepEntries/4",
      "createTime": "2023-10-21T15:25:55.412992302Z",
      "updateTime": "2023-10-21T15:25:55.412998396Z",
      "routine": "main",
      "step": "retStep",
      "stepType": "STEP_RETURN",
      "state": "STATE_SUCCEEDED",
      "entryId": "4",
      "navigationInfo": {
        "previous": "3"
      }
    }
  ],
  "totalSize": 4
}

Workflow with a failed step entry

Workflow

YAML

- tryStep:
    try:
      return: ${1 / 0}
    except:
      return: 0

JSON

[
  {
    "tryStep": {
      "try": {
        "return": "${1 / 0}"
      },
      "except": {
        "return": 0
      }
    }
  }
]

Diagram

Workflow with a failed step entry

Step entries

{
  "stepEntries": [
    {
      "name": "projects/200478149810/locations/us-central1/workflows/ck-for-block/executions/8ec49dae-ab0c-4b55-b1c4-b809244be913/stepEntries/1",
      "createTime": "2023-10-20T18:06:50.395938752Z",
      "updateTime": "2023-10-20T18:06:50.396525946Z",
      "routine": "main",
      "step": "tryStep",
      "stepType": "STEP_TRY_RETRY_EXCEPT",
      "state": "STATE_SUCCEEDED",
      "entryId": "1",
      "navigationInfo": {
        "children": [
          "2",
          "4"
        ],
        "next": "2"
      }
    },
    {
      "name": "projects/200478149810/locations/us-central1/workflows/ck-for-block/executions/8ec49dae-ab0c-4b55-b1c4-b809244be913/stepEntries/2",
      "createTime": "2023-10-20T18:06:50.395942598Z",
      "updateTime": "2023-10-20T18:06:50.396497992Z",
      "routine": "main",
      "step": "tryStep",
      "stepType": "STEP_TRY",
      "state": "STATE_FAILED",
      "entryId": "2",
      "navigationInfo": {
        "children": [
          "3"
        ],
        "parent": "1",
        "next": "3",
        "previous": "1"
      }
    },
    {
      "name": "projects/200478149810/locations/us-central1/workflows/ck-for-block/executions/8ec49dae-ab0c-4b55-b1c4-b809244be913/stepEntries/3",
      "createTime": "2023-10-20T18:06:50.395944871Z",
      "updateTime": "2023-10-20T18:06:50.396497499Z",
      "routine": "main",
      "step": "tryStep.try",
      "stepType": "STEP_RETURN",
      "state": "STATE_FAILED",
      "exception": {
        "payload": "{\"message\":\"ZeroDivisionError: division by zero\",\"tags\":[\"ZeroDivisionError\",\"ArithmeticError\"]}"
      },
      "entryId": "3",
      "navigationInfo": {
        "parent": "2",
        "next": "4",
        "previous": "2"
      }
    },
    {
      "name": "projects/200478149810/locations/us-central1/workflows/ck-for-block/executions/8ec49dae-ab0c-4b55-b1c4-b809244be913/stepEntries/4",
      "createTime": "2023-10-20T18:06:50.396506860Z",
      "updateTime": "2023-10-20T18:06:50.396525900Z",
      "routine": "main",
      "step": "tryStep",
      "stepType": "STEP_EXCEPT",
      "state": "STATE_SUCCEEDED",
      "entryId": "4",
      "navigationInfo": {
        "children": [
          "5"
        ],
        "parent": "1",
        "next": "5",
        "previous": "3"
      }
    },
    {
      "name": "projects/200478149810/locations/us-central1/workflows/ck-for-block/executions/8ec49dae-ab0c-4b55-b1c4-b809244be913/stepEntries/5",
      "createTime": "2023-10-20T18:06:50.396516994Z",
      "updateTime": "2023-10-20T18:06:50.396525818Z",
      "routine": "main",
      "step": "tryStep.except",
      "stepType": "STEP_RETURN",
      "state": "STATE_SUCCEEDED",
      "entryId": "5",
      "navigationInfo": {
        "parent": "4",
        "previous": "4"
      }
    }
  ],
  "totalSize": 5
}

What's next