# AWS Step Functions

ARNscope follows a Step Functions run while it happens. A running execution opens on a graph that updates as each state finishes, and any state shows its input, its output, every attempt with its error and the logs its Lambda function or ECS task wrote, beside the graph. A timeline and the full event history cover the same run. Stop and redrive always ask first.

<figure class="doc-video">
<video controls playsinline preload="none" poster="/media/docs/sfn/sfn-explainer.webp?v=1" aria-label="Step Functions in ARNscope: a narrated tour of about ninety seconds">
<source src="/media/docs/sfn/sfn-explainer.webm?v=1" type="video/webm">
<source src="/media/docs/sfn/sfn-explainer.mp4?v=1" type="video/mp4">
<track kind="captions" srclang="en" label="English" src="/media/docs/sfn/sfn-explainer.vtt?v=1" default>
</video>
<figcaption>A narrated tour of about ninety seconds, with captions: a run followed live, a state's input and output, a retry, Live Tail, the timeline and events, a failed run and redrive. Sample data.</figcaption>
</figure>

## State machines and runs

Open **Step Functions** in ARNscope and choose the profile and region. The list shows every state machine; Express workflows are marked **EXP**. Select one to open it.

| Tab | What it shows |
| --- | --- |
| **Executions** | The runs, newest first, with a summary strip and a chart of recent runs |
| **Definition** | The definition as a graph (click a state for its settings) or as JSON |
| **Details** | ARN, type, execution role, revision, logging level and log groups, X-Ray tracing |

Above the executions, a strip shows the success rate, failed and running runs, the median and p95 duration and the slowest run. **Recent runs** draws each run as a bar: its height is the duration, its colour the outcome. Click a bar to open that run. Filter the list by status (**Running**, **Succeeded**, **Failed**, **Timed out**, **Aborted**) or by name.

<figure class="doc-clip">
<video data-clip controls muted loop playsinline preload="none" poster="/media/docs/sfn/sfn-runs.webp?v=1" aria-label="The order-fulfilment executions: success rate, failures, running runs and median duration, the recent-runs chart, then the Failed and Running filters.">
<source src="/media/docs/sfn/sfn-runs.webm?v=1" type="video/webm">
<source src="/media/docs/sfn/sfn-runs.mp4?v=1" type="video/mp4">
</video>
<figcaption>The executions: the summary strip, recent runs by duration and outcome, and the status filters.</figcaption>
</figure>

The first 100 runs show at once; older pages load in the background, up to 2,000, and **Load older** reads further back. Status filters and the name filter work on what is loaded.

Express workflows keep no execution history in Step Functions, so their **Executions** tab says where their runs are logged instead. You can still start one.

## A run, live

Open a run and it shows on the graph. Each state is coloured by what happened to it: **Succeeded**, **Caught**, **Failed**, **Running** or not run, and the path the run took is drawn in. Parallel branches and Map processors sit inside their state. Each state shows its time, how many times it ran, and **↻** with the number of retries. Zoom with ⌘-scroll or the buttons, drag to pan, and **Fit graph** to see it all.

While the run is going, ARNscope reads it again every five seconds (not while the window is hidden), so states light up as they finish. It opens on the state that is running, or the one that failed.

<figure class="doc-clip">
<video data-clip controls muted loop playsinline preload="none" poster="/media/docs/sfn/sfn-live-graph.webp?v=1" aria-label="A running order waits in Manual review; the analyst approves, Calculate tax runs and the Reserve inventory Map fans out its items.">
<source src="/media/docs/sfn/sfn-live-graph.webm?v=1" type="video/webm">
<source src="/media/docs/sfn/sfn-live-graph.mp4?v=1" type="video/mp4">
</video>
<figcaption>The analyst approves, and the run moves on into the Map: each item runs as its own iteration.</figcaption>
</figure>

A strip above the graph sums up the run: its duration, the states and transitions so far, the retries, the slowest state, and the largest payload against Step Functions' 256 KB limit.

## A state's input, output and attempts

Click a state for its details: how long it took, when it was entered, its attempts, the size of its input and output, then the input and output themselves and the state's definition, with its target, retries and catchers. A state that ran more than once, such as a Map iteration or a state in a loop, has a **Visit** menu to pick which run of it to show.

<figure class="doc-clip">
<video data-clip controls muted loop playsinline preload="none" poster="/media/docs/sfn/sfn-state-io.webp?v=1" aria-label="Clicking Score rules: its duration, attempts and payload sizes, then its input and output JSON.">
<source src="/media/docs/sfn/sfn-state-io.webm?v=1" type="video/webm">
<source src="/media/docs/sfn/sfn-state-io.mp4?v=1" type="video/mp4">
</video>
<figcaption>A state's input and output, and how long it took.</figcaption>
</figure>

A retried state lists every attempt with its outcome, its time, the backoff before it and the error that ended it. An error shows its name, its message and, for Lambda and Python errors, the stack trace.

<figure class="doc-clip">
<video data-clip controls muted loop playsinline preload="none" poster="/media/docs/sfn/sfn-retries.webp?v=1" aria-label="Score ML model shows one retry on the graph; its details list Attempt 1 failed with FraudModel.EndpointTimeout and Attempt 2 OK after a 2-second backoff, and the stack trace opens.">
<source src="/media/docs/sfn/sfn-retries.webm?v=1" type="video/webm">
<source src="/media/docs/sfn/sfn-retries.mp4?v=1" type="video/mp4">
</video>
<figcaption>A retry after a timeout: every attempt, the backoff between them, and the error with its stack trace.</figcaption>
</figure>

## A state's logs and Live Tail

The **Logs** tab beside **Details** shows what the state wrote:

| The state ran | Logs shown |
| --- | --- |
| A Lambda function | The function's log group (`/aws/lambda/<name>`), for the time the state ran |
| An ECS task | Each container's awslogs stream for the task, merged by time |
| Anything else | The state machine's own log group, filtered to this execution, when logging is on |

Pick another source from the menu, such as the state machine log, and filter the lines as you type. Up to 1,000 lines are read.

<figure class="doc-clip">
<video data-clip controls muted loop playsinline preload="none" poster="/media/docs/sfn/sfn-step-logs.webp?v=1" aria-label="Score ML model's Logs tab: the fraud-score-ml function's lines for the run, filtered to the word score.">
<source src="/media/docs/sfn/sfn-step-logs.webm?v=1" type="video/webm">
<source src="/media/docs/sfn/sfn-step-logs.mp4?v=1" type="video/mp4">
</video>
<figcaption>The Lambda function's logs for a step, beside the graph.</figcaption>
</figure>

While a state is still running, **Live tail** streams new lines as they are written, with CloudWatch Logs Live Tail. It stops when you leave the Logs tab or the page, keeps the newest 2,000 lines, and says when CloudWatch is sampling a busy group. Live Tail is billed by CloudWatch per minute.

<figure class="doc-clip">
<video data-clip controls muted loop playsinline preload="none" poster="/media/docs/sfn/sfn-live-tail.webp?v=1" aria-label="Reserve stock is running inside the Map; its Logs tab starts Live tail and new lines from the inventory-reserve function arrive.">
<source src="/media/docs/sfn/sfn-live-tail.webm?v=1" type="video/webm">
<source src="/media/docs/sfn/sfn-live-tail.mp4?v=1" type="video/mp4">
</video>
<figcaption>Live Tail on a step that is still running.</figcaption>
</figure>

## Timeline, events, input and output

**Timeline** puts every state on one time axis: each visit is a bar, red ticks mark failed attempts that were retried, and the last columns give each state's total time and share of the run. Parallel and Map states include the time of the states inside them. Click a row to open that state.

<figure class="doc-clip">
<video data-clip controls muted loop playsinline preload="none" poster="/media/docs/sfn/sfn-timeline.webp?v=1" aria-label="The timeline: Manual review takes most of the run; Score ML model shows a retry; clicking Reserve stock opens its details.">
<source src="/media/docs/sfn/sfn-timeline.webm?v=1" type="video/webm">
<source src="/media/docs/sfn/sfn-timeline.mp4?v=1" type="video/mp4">
</video>
<figcaption>Every state, attempt and retry on one axis, so slow steps stand out.</figcaption>
</figure>

**Events** is the full execution history, with the time from the start, the type, the state and a detail column. Filter it to **Failures**, **Transitions** or **Tasks**, or by text; click an event for its JSON, with embedded JSON strings expanded. **Input & output** shows the execution's own input and output.

<figure class="doc-clip">
<video data-clip controls muted loop playsinline preload="none" poster="/media/docs/sfn/sfn-events.webp?v=1" aria-label="The Events tab filtered to Transitions, then Failures; the first TaskFailed event opens as JSON.">
<source src="/media/docs/sfn/sfn-events.webm?v=1" type="video/webm">
<source src="/media/docs/sfn/sfn-events.mp4?v=1" type="video/mp4">
</video>
<figcaption>The event history, filtered to failures, with an event's JSON.</figcaption>
</figure>

## A failed run

A failed, timed-out or aborted run opens on the state that broke. A banner above the graph names it and shows the error, its message and the stack trace when there is one.

<figure class="doc-clip">
<video data-clip controls muted loop playsinline preload="none" poster="/media/docs/sfn/sfn-failed-run.webp?v=1" aria-label="A failed order: Failed in Authorize payment, PaymentProvider.Unavailable, Card gateway returned 503 Service Unavailable, and the stack trace.">
<source src="/media/docs/sfn/sfn-failed-run.webm?v=1" type="video/webm">
<source src="/media/docs/sfn/sfn-failed-run.mp4?v=1" type="video/mp4">
</video>
<figcaption>A failed run opens on the state that broke.</figcaption>
</figure>

## Stop, redrive and run again

These change things in your account, so each one asks first:

- **Stop** (running runs) asks in a red bar, with the profile and region. Steps in progress are not rolled back.
- **Redrive** (failed runs that Step Functions can redrive) restarts the run from the step that failed; steps that already succeeded are not run again. After you confirm, ARNscope follows the execution until the redrive shows up and says how it ended.
- **Run again** opens **Start execution** with the run's input, for you to edit. The dialog says the run is for real and names the profile and region.

<figure class="doc-clip">
<video data-clip controls muted loop playsinline preload="none" poster="/media/docs/sfn/sfn-redrive.webp?v=1" aria-label="Redrive on the failed order: the confirm bar says it restarts from the step that failed and names the profile and region; after Redrive now the run follows the redrive.">
<source src="/media/docs/sfn/sfn-redrive.webm?v=1" type="video/webm">
<source src="/media/docs/sfn/sfn-redrive.mp4?v=1" type="video/mp4">
</video>
<figcaption>Redrive asks before anything runs, then follows the run.</figcaption>
</figure>

A run whose error was caught and that ended in a **Fail** state would fail again at once if redriven, with no step rerun. ARNscope says so in the bar, offers **Run again** instead, and keeps **Redrive anyway** for when you mean it.

<figure class="doc-clip">
<video data-clip controls muted loop playsinline preload="none" poster="/media/docs/sfn/sfn-redrive-fail-state.webp?v=1" aria-label="Redrive on an order that ended in the Fail state Order cancelled: the bar explains that Authorize payment failed and was caught, so a redrive restarts at Order cancelled and reruns no step, and offers Run again.">
<source src="/media/docs/sfn/sfn-redrive-fail-state.webm?v=1" type="video/webm">
<source src="/media/docs/sfn/sfn-redrive-fail-state.mp4?v=1" type="video/mp4">
</video>
<figcaption>A run that ended in a Fail state gets a warning instead.</figcaption>
</figure>

Buttons your role cannot use are disabled, with the reason from the [IAM permission check](https://arnscope.com/docs/iam-permission-check).

## Permissions

| What | Actions |
| --- | --- |
| List state machines | `states:ListStateMachines` |
| Definition and details | `states:DescribeStateMachine` |
| Executions | `states:ListExecutions` |
| A run | `states:DescribeExecution`, `states:DescribeStateMachineForExecution`, `states:GetExecutionHistory` |
| Logs | `logs:FilterLogEvents` (Lambda and state machine logs); `ecs:DescribeTaskDefinition` and `logs:GetLogEvents` (ECS tasks) |
| Live Tail | `logs:StartLiveTail`, `logs:DescribeLogGroups` |
| Start, run again | `states:StartExecution` |
| Stop | `states:StopExecution` |
| Redrive | `states:RedriveExecution` |

## Limitations

- Express workflows have no execution list or run view; their runs are in CloudWatch Logs.
- A run with more than 10,000 history events shows the first 10,000.
- Inputs and outputs larger than Step Functions returns are not shown, and such a run cannot be used for **Run again**.
- Lambda logs are read from the default log group, `/aws/lambda/<name>`; a function with a custom log group shows nothing. Lines from other invocations in the same time window may appear.
- ECS task logs need an `awslogs` stream prefix. At most 20 task streams are read, and Live Tail follows only the streams in the first container's log group.
- Map Runs (distributed Map) and activity workers have no log source of their own.

Source: https://arnscope.com/docs/step-functions
