How Step Functions associates executions with a version or alias
Step Functions associates an execution with a version or alias based on the Amazon Resource Name (ARN) that you use to invoke the StartExecution API action. Step Functions performs this action at the execution start time.
You can start a state machine execution using a qualified or an unqualified ARN.
-
Qualified ARN – Refers to a state machine ARN suffixed with a version number or an alias name.
The following qualified ARN example refers to version
3
of a state machine namedmyStateMachine
.arn:aws-cn:
states:us-east-1
:123456789012
:stateMachine:myStateMachine
:3The following qualified ARN example refers to an alias named
PROD
of a state machine namedmyStateMachine
.arn:aws-cn:
states:us-east-1
:123456789012
:stateMachine:myStateMachine
:PROD
-
Unqualified ARN – Refers to a state machine ARN without a version number or an alias name suffix.
arn:aws-cn:
states:us-east-1
:123456789012
:stateMachine:myStateMachine
For example, if your qualified ARN refers to version 3
, Step Functions associates the
execution with this version. It doesn't associate the execution with any aliases that point
to the version 3
.
If your qualified ARN refers to an alias, Step Functions associates the execution with that alias and the version to which the alias points. An execution can only be associated with one alias.
Note
If you start an execution with an unqualified ARN, Step Functions doesn't associate that execution with a version even if the version uses the same state machine revision. For example, if version 3 uses the latest revision, but you start an execution with an unqualified ARN, Step Functions doesn't associate that execution with the version 3.
Viewing executions started with a version or an alias
Step Functions provides the following ways in which you can view the executions started with a version or an alias:
Using API actions
You can view all the executions associated with a version or an alias by invoking the DescribeExecution and ListExecutions API actions. These API actions return the ARN of the version or alias that was used to start the execution. These actions also return other details including status and ARN of the execution.
You can also provide a state machine alias ARN or version ARN to list the executions associated with a specific alias or version.
The following example response of the ListExecutions API action shows the ARN of the alias used to start
a state machine execution named myFirstExecution
.
The italicized
text in the following code snippet represents resource-specific information.
{
"executions": [
{
"executionArn": "arn:aws-cn:states:us-east-1
:123456789012
:execution:myStateMachine:myFirstExecution
",
"stateMachineArn": "arn:aws-cn:states:us-east-1
:123456789012
:stateMachine:myStateMachine
",
"stateMachineAliasArn": "arn:aws-cn:states:us-east-1
:123456789012
:stateMachine:myStateMachine:PROD
",
"name": "myFirstExecution
",
"status": "SUCCEEDED",
"startDate": "2023-04-20T23:07:09.477000+00:00",
"stopDate": "2023-04-20T23:07:09.732000+00:00"
}
]
}
Using Step Functions console
You can also view the executions started by a version or an alias from the Step Functions
console
-
Open the Step Functions console
, and then choose an existing state machine for which you've published a version or created an alias. This example shows how to view the executions started with a specific state machine version. -
Choose the Versions tab, and then choose a version from the Versions list.
Tip
Filter by property or value box to search for a specific version.
-
On the Version details page, you can see a list of all the in-progress and past state machine executions started with the selected version.
The following image shows the Version Details console page. This page lists executions started by the version 4 of a state machine named
. This list also displays an execution that was started by an alias named MathAddDemo
. This alias routed the execution traffic to version 4.PROD
Using CloudWatch metrics
For each state machine execution that you start with a Qualified ARN, Step Functions emits additional metrics with the same name and value as the metrics emitted currently. These additional metrics contain dimensions for each of the version identifier and alias name with which you start an execution. With these metrics, you can monitor state machine executions at the version level and determine when a rollback scenario might be necessary. You can also create Amazon CloudWatch alarms based on these metrics.
Step Functions emits the following metrics for executions that you start with an alias or a version:
-
ExecutionTime
-
ExecutionsAborted
-
ExecutionsFailed
-
ExecutionsStarted
-
ExecutionsSucceeded
-
ExecutionsTimedOut
If you started the execution with a version ARN, Step Functions publishes the metric with the StateMachineArn
and a second metric with StateMachineArn
and Version
dimensions.
If you started the execution with an alias ARN, Step Functions emits the following metrics:
-
Two metrics for the unqualified ARN and version.
-
A metric with the
StateMachineArn
andAlias
dimensions.