prefect.server.orchestration.global_policy

Bookkeeping logic that fires on every state transition.

For clarity, GlobalFlowpolicy and GlobalTaskPolicy contain all transition logic implemented using BaseUniversalTransform. None of these operations modify state, and regardless of what orchestration Prefect REST API might enforce on a transition, the global policies contain Prefect's necessary bookkeeping. Because these transforms record information about the validated state committed to the state database, they should be the most deeply nested contexts in orchestration loop.

Functions

COMMON_GLOBAL_TRANSFORMS ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/global_policy.py#L34" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

COMMON_GLOBAL_TRANSFORMS() -> list[type[BaseUniversalTransform[orm_models.Run, Union[core.FlowRunPolicy, core.TaskRunPolicy]]]]

Classes

GlobalFlowPolicy ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/global_policy.py#L54" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

Global transforms that run against flow-run-state transitions in priority order.

These transforms are intended to run immediately before and after a state transition is validated.

Methods:

priority ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/global_policy.py#L63" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

priority() -> list[Union[type[BaseUniversalTransform[orm_models.FlowRun, core.FlowRunPolicy]], type[BaseOrchestrationRule[orm_models.FlowRun, core.FlowRunPolicy]]]]

GlobalTaskPolicy ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/global_policy.py#L87" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

Global transforms that run against task-run-state transitions in priority order.

These transforms are intended to run immediately before and after a state transition is validated.

Methods:

priority ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/global_policy.py#L96" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

priority() -> list[Union[type[BaseUniversalTransform[orm_models.TaskRun, core.TaskRunPolicy]], type[BaseOrchestrationRule[orm_models.TaskRun, core.TaskRunPolicy]]]]

SetRunStateType ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/global_policy.py#L115" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

Updates the state type of a run on a state transition.

Methods:

before_transition ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/global_policy.py#L124" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

before_transition(self, context: GenericOrchestrationContext[orm_models.Run, Any]) -> None

SetRunStateName ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/global_policy.py#L135" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

Updates the state name of a run on a state transition.

Methods:

before_transition ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/global_policy.py#L144" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

before_transition(self, context: GenericOrchestrationContext[orm_models.Run, Any]) -> None

SetStartTime ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/global_policy.py#L155" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

Records the time a run enters a running state for the first time.

Methods:

before_transition ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/global_policy.py#L164" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

before_transition(self, context: GenericOrchestrationContext[orm_models.Run, Any]) -> None

SetRunStateTimestamp ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/global_policy.py#L177" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

Records the time a run changes states.

Methods:

before_transition ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/global_policy.py#L186" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

before_transition(self, context: GenericOrchestrationContext[orm_models.Run, Any]) -> None

SetEndTime ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/global_policy.py#L197" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

Records the time a run enters a terminal state.

With normal client usage, a run will not transition out of a terminal state. However, it's possible to force these transitions manually via the API. While leaving a terminal state, the end time will be unset.

Methods:

before_transition ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/global_policy.py#L210" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

before_transition(self, context: GenericOrchestrationContext[orm_models.Run, Any]) -> None

IncrementRunTime ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/global_policy.py#L235" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

Records the amount of time a run spends in the running state.

Methods:

before_transition ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/global_policy.py#L244" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

before_transition(self, context: GenericOrchestrationContext[orm_models.Run, Any]) -> None

IncrementFlowRunCount ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/global_policy.py#L259" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

Records the number of times a run enters a running state. For use with retries.

Methods:

before_transition ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/global_policy.py#L266" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

before_transition(self, context: OrchestrationContext[orm_models.FlowRun, core.FlowRunPolicy]) -> None

RemoveResumingIndicator ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/global_policy.py#L285" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

Removes the indicator on a flow run that marks it as resuming.

Methods:

before_transition ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/global_policy.py#L292" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

before_transition(self, context: OrchestrationContext[orm_models.FlowRun, core.FlowRunPolicy]) -> None

IncrementTaskRunCount ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/global_policy.py#L311" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

Records the number of times a run enters a running state. For use with retries.

Methods:

before_transition ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/global_policy.py#L316" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

before_transition(self, context: OrchestrationContext[orm_models.TaskRun, core.TaskRunPolicy]) -> None

SetExpectedStartTime ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/global_policy.py#L330" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

Estimates the time a state is expected to start running if not set.

For scheduled states, this estimate is simply the scheduled time. For other states, this is set to the time the proposed state was created by Prefect.

Methods:

before_transition ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/global_policy.py#L342" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

before_transition(self, context: GenericOrchestrationContext[orm_models.Run, Any]) -> None

SetNextScheduledStartTime ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/global_policy.py#L358" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

Records the scheduled time on a run.

When a run enters a scheduled state, run.next_scheduled_start_time is set to the state's scheduled time. When leaving a scheduled state, run.next_scheduled_start_time is unset.

Methods:

before_transition ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/global_policy.py#L371" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

before_transition(self, context: GenericOrchestrationContext[orm_models.Run, Any]) -> None

UpdateSubflowParentTask ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/global_policy.py#L388" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

Whenever a subflow changes state, it must update its parent task run's state.

Methods:

after_transition ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/global_policy.py#L395" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

after_transition(self, context: OrchestrationContext[orm_models.FlowRun, core.FlowRunPolicy]) -> None

UpdateSubflowStateDetails ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/global_policy.py#L420" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

Update a child subflow state's references to a corresponding tracking task run id in the parent flow run

Methods:

before_transition ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/global_policy.py#L428" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

before_transition(self, context: OrchestrationContext[orm_models.FlowRun, core.FlowRunPolicy]) -> None

UpdateStateDetails ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/global_policy.py#L444" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

Update a state's references to a corresponding flow- or task- run.

Methods:

before_transition ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/orchestration/global_policy.py#L453" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

before_transition(self, context: GenericOrchestrationContext) -> None