Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add state transition table to 'Manage states' doc and link from the debug tutorial #16668

Open
wants to merge 4 commits into
base: main
Choose a base branch
from
Open

Add state transition table to 'Manage states' doc and link from the debug tutorial #16668

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
57caeac
Add a link to the 'Manage states' docs
daniel-prefect Jan 9, 2025
6fbac20
Add a section on state transitions to the 'Manage states' how to
daniel-prefect Jan 9, 2025
b8fdb95
Improve copy
daniel-prefect Jan 9, 2025
e7cf4aa
Clarify that a late run can be triggered by either cloud or a self-ho…
daniel-prefect Jan 9, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 16 additions & 0 deletions docs/v3/develop/manage-states.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,6 +49,22 @@ The full list of states and state types includes:
| `Failed` | `FAILED` | Yes | The run did not complete because of a code issue and had no remaining retry attempts. |
| `Crashed` | `CRASHED` | Yes | The run did not complete because of an infrastructure issue. |

## State transitions

When a flow run changes states, you can often tell if it is behaving normally or not.
Here are some common state transitions and what they mean:

| | From | To | Triggered By | Explanation |
| --- | --------------- | ------------ | ----------- | ----------- |
| ✅ | None | Scheduled | Cloud (schedule) or user (custom run) | A flow run has been created and scheduled for future execution. |
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
| ✅ | None | Scheduled | Cloud (schedule) or user (custom run) | A flow run has been created and scheduled for future execution. |
| ✅ | None | Scheduled | Manual run, automation, or schedule | A flow run has been created and scheduled for future execution. |

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could be automation and could be quick or custom run and might be from Cloud or self-hosted Prefect server, so I think something like my suggestion is more accurate.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

cc @EmilRex ^

| ✅ | Scheduled | Pending | Worker | A worker is attempting to start the infrastructure for your flow run. |
| ⛔ | Scheduled | Late | Cloud or self-hosted server | Typically means that a worker did not pick up the run because 1) no workers are healthy, 2) workers are not polling the right work pool or work queue, or 3) workers are concurrency limited. |
| ✅ | Pending | Running | Worker | The infrastructure was provisioned and the flow is running |
| ⛔ | Pending | Crashed | Worker or runner | Something went wrong. Some possibilities are 1) the worker could have failed to create the infrastructure, 2) the code is not present in storage or the worker failed to authenticate, or 3) the code has missing or broken imports, or syntax errors. |
| ✅ | Running | Completed | Flow run | The flow completed successfully. |
| ⛔ | Running | Failed | Flow run | This usually means that your code raised an exception, check the flow run logs. |
| ⛔ | Running | Crashed | Worker or flow run | Probably not a raised exception in your code, but could be an infrastructure issue such as 1) an out of memory error, 2) an evicted pod, or 3) a timeout. |

## Final state determination

The final state of a flow or task run depends on a number of factors; generally speaking there are three categories of terminal states:
Expand Down
1 change: 1 addition & 0 deletions docs/v3/tutorials/debug.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -112,6 +112,7 @@ python simulate_failures.py
## Next steps

In this tutorial, you successfully used Prefect Cloud to fix a failing data pipeline.
To learn more about the different states that can occur during the flow run lifecycle, see [Manage states](/v3/develop/manage-states).

Next, learn how to [alert your team](/v3/tutorials/alerts) when failures occur.

Expand Down
Loading