diff --git a/docs/developer-guides/debugging-workflows.md b/docs/developer-guides/debugging-workflows.md index b9d3aeae..34b40f71 100644 --- a/docs/developer-guides/debugging-workflows.md +++ b/docs/developer-guides/debugging-workflows.md @@ -5,59 +5,71 @@ import Install from '@site/src/components/install.mdx'; # Debugging Workflows -Orkes Conductor provides a visual representation of workflows that aids in quickly troubleshooting issues. Conductor UI provides you with the ability to look into workflow executions, which helps quickly spot and resolve issues. +Orkes Conductor provides a visual representation of workflows that aids in quickly troubleshooting issues. The Conductor UI allows users to inspect workflow executions, facilitating rapid identification and resolution of problems. -## Searching/Viewing Workflow Executions +## Searching and Viewing Workflow Executions​ -All recent workflow executions are listed on the **Executions > Workflow** page. This view is filtered by the user's permissions by default, i.e., users can view the execution of only the permitted workflows. +All recent workflow executions are listed on the **Executions > Workflow** page. By default, users can only view executions of permitted workflows.

Workflow Executions page

-The workflow execution data can be filtered by searching through workflow name, workflow ID, correlation ID, idempotency key, status, time period, and free text search. Click on the required execution to view the individual execution of a workflow. +The workflow execution data can be filtered by searching through workflow name, workflow ID, correlation ID, idempotency key, status, time period, and free text search. Turn on **SQL format** to view the workflow execution data in SQL format. -In addition, you can view the workflow execution as code directly from the UI. To do this, click the arrow in the Search button and choose “**Show as code”**. +Additionally, you can view the workflow execution as code directly from the UI by clicking the arrow in the Search button and selecting **Show as code**.

Show as code option in Workflow Search

-This would show the workflow search data in different codes. Currently, you can get them in cURL and Javascript. +This would show the workflow search data in different codes. You can get the workflow search data in cURL and Javascript formats. +

Workflow search data in code

:::note -You can also search for workflow names by inputting partial values with wildcards (*) support. For example, if you want to search for workflow names containing “test”, then search for **test***, which will display all the workflow definitions with **‘test’** in their name. +Partial searches using wildcards `*` are supported for workflow names. For example, searching for **test*** will display all workflows with names containing "test". +

Workflow search with wildcard support

::: -A sample execution looks like this: +### Viewing Individual Workflow Execution + +Click on a specific execution to view detailed information. A sample execution looks like this:

Sample Workflow Executions page

The page consists of the following sub-tabs: -* **Diagram** - Shows the visual representation of the workflow. If the workflow isn’t completed/failed, the diagram indicates the same. -* **Task List** - Includes the details of the tasks within the workflow. -* **Timeline** - A timeline showing the time taken by different tasks for execution. You can also zoom around the task timeline for more accuracy. -* **Summary** - Includes the workflow details such as workflow ID, status, version, start/end time, and duration. -* **Workflow Input/Output** - Shows the list of the inputs and outputs of the workflow. -* **JSON** - Include the complete JSON of the workflow. +* **Diagram** - Visual representation of the workflow's status; tasks are color-coded (green for successful, red for failed, orange for completed with errors). +* **Task List** - Details of tasks within the workflow. +* **Timeline** - Chronological timeline of task execution times, with zoom functionality for accuracy. +* **Summary** - Includes key details such as workflow ID, status, version, start/end time, and duration. +* **Workflow Input/Output** - Lists inputs and outputs of the workflow. +* **JSON** - Complete JSON representation of the workflow. +* **Variables** - Displays variables passed using the set variable task. +* **Task To Domain** - Mapping of tasks to domains used in the workflow execution. Each of these tabs gives the details that can help debug workflow issues. ## Debugging Executions -The diagram tab on the workflow execution page shows the workflow diagram. All the successful tasks appear in green, failed ones appear in red, and the ones completed with errors appear in orange. +The **Diagram** tab on the workflow execution page visually represents task statuses: + +

Different types of errors in a failed workflow

+ +* Green: Successful tasks +* Red: Failed tasks +* Orange: Tasks completed with errors + :::tip A task ends up with the status “Completed with Errors” only when it is marked as __optional:true__ in the workflow definition. The default value of this setting is false, so it needs to be explicitly set to continue the workflow even when there are errors. ::: -

Different types of errors in a failed workflow

Clicking on the failed task gives the failure details. The following fields are helpful in debugging: @@ -72,22 +84,22 @@ Clicking on the failed task gives the failure details. The following fields are Here is a screen grab of the fields referred above. -

Failure reasons for the task

+

Failure reasons for the task

## Recovering From Failures​ -Once the issues are resolved for the workflow execution failure, you might want to retry the failed workflows. The **Actions** button towards the top-right corner of the execution page provides the following options: +Once the issues regarding the workflow execution failure are resolved, you can retry the failed workflows. The **Actions** button towards the top-right corner of the execution page provides the following options:

Workflow Recovery Options

| Action | Description | | ------ |-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Terminate | Terminates the workflow and changes the workflow status to **TERMINATED**. | -| Restart with Current Definitions | Restart the workflow from the beginning using the same version of the workflow definition that originally ran this execution. This is useful if the workflow definition has changed and you want to retain this instance in the original version. | -| Restart with Latest Definitions | Restart this workflow from the beginning using the latest definition of the workflow. If you've made changes to the definition, you could use this option to re-run the flow with the latest version. | -| Retry - From failed task | Retries the workflow from the failed task. | -| Re-run Workflow | Clicking on this takes us to the **Run Workflow** page, where you can rerun the workflow. While running, you can change the workflow input parameters and task to domain mapping. | +| Restart with current definitions | Restart the workflow from the beginning using the same version of the workflow definition that originally ran this execution. This is useful if the workflow definition has changed and you want to retain this instance of the original version. | +| Restart with latest definitions | Restart this workflow from the beginning using the latest definition of the workflow. If you've made changes to the definition, you could use this option to re-run the flow with the latest version. | +| Retry - from failed task | Retries the workflow from the failed task. | +| Re-run Workflow | Clicking on this takes to the **Run Workflow** page, where you can rerun the workflow. While running, you can change the workflow input parameters, idempotency key, correlation ID, and task to domain mapping. | :::tip -Orkes Conductor has native [retry and error handling](https://orkes.io/content/error-handling) capabilities, allowing your task to be retried automatically for transient failures. +Check out the documentation on native [retry and error handling](https://orkes.io/content/error-handling) features, which enable tasks to be automatically retried in the event of transient failures. ::: \ No newline at end of file diff --git a/static/img/failure-reasons-of-task.png b/static/img/failure-reasons-of-task.png new file mode 100644 index 00000000..0f9b05d5 Binary files /dev/null and b/static/img/failure-reasons-of-task.png differ diff --git a/static/img/show-as-code-in-workflow-search.png b/static/img/show-as-code-in-workflow-search.png index 3ca7944d..c625ff7f 100644 Binary files a/static/img/show-as-code-in-workflow-search.png and b/static/img/show-as-code-in-workflow-search.png differ diff --git a/static/img/workflow-executions.png b/static/img/workflow-executions.png index c23e214a..66042b5f 100644 Binary files a/static/img/workflow-executions.png and b/static/img/workflow-executions.png differ diff --git a/static/img/workflow-partial-search.png b/static/img/workflow-partial-search.png index fba33ed1..58683f79 100644 Binary files a/static/img/workflow-partial-search.png and b/static/img/workflow-partial-search.png differ diff --git a/static/img/workflow-recovery.png b/static/img/workflow-recovery.png index 3168fb6c..d827645c 100644 Binary files a/static/img/workflow-recovery.png and b/static/img/workflow-recovery.png differ diff --git a/static/img/workflow-search-in-code.png b/static/img/workflow-search-in-code.png index 78e5ca47..220853a5 100644 Binary files a/static/img/workflow-search-in-code.png and b/static/img/workflow-search-in-code.png differ