Step Functions에서 오류 처리 - AWS Step Functions

기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

Step Functions에서 오류 처리

PassWait 상태를 제외한 모든 상태에서 런타임 오류가 발생할 수 있습니다. 다음 예제와 같은 다양한 이유로 오류가 발생할 수 있습니다.

  • 상태 머신 정의 문제(예: Choice 상태에 일치하는 규칙 없음)

  • 작업 실패(예: AWS Lambda 함수에서 예외 발생)

  • 일시적인 문제(예: 네트워크 파티션 이벤트)

기본적으로, 상태가 오류를 보고하는 경우 AWS Step Functions에서 실행에 전체적으로 오류를 발생시킵니다.

작은 정보

오류 처리가 포함된 워크플로 예제를 AWS 계정에 배포하려면 AWS Step Functions 워크숍모듈 8 - 오류 처리를 참조하세요.

오류 이름

Step Functions는 오류 이름이라고 하는 대소문자를 구분하는 문자열을 사용하여 Amazon States Language의 오류를 식별합니다. Amazon States Language는 잘 알려진 오류의 이름을 지정하는 기본 제공 문자열 집합을 정의하며,모든 문자열은 States. 접두사로 시작합니다.

States.ALL

확인된 오류 이름과 일치하는 와일드카드.

참고

이 오류 유형은 States.DataLimitExceeded 터미널 오류 유형과 런타임 오류 유형을 포착할 수 없습니다. 이러한 오류 유형에 대한 자세한 내용은 States.DataLimitExceededStates.Runtime을 참조하세요.

States.DataLimitExceeded

Step Functions는 다음 조건에서 States.DataLimitExceeded 예외를 보고합니다.

  • 커넥터 출력이 페이로드 크기 할당량보다 큰 경우

  • 상태 출력이 페이로드 크기 할당량보다 큰 경우

  • Parameters 처리 후 상태 입력이 페이로드 크기 할당량보다 큰 경우

할당량에 대한 자세한 내용은 할당량을 참조하세요.

참고

이 오류는 States.ALL 오류 유형에서 포착할 수 없는 터미널 오류입니다.

States.ExceedToleratedFailureThreshold

실패한 항목 수가 상태 시스템 정의에 지정된 임계값을 초과하므로 Map 상태가 실패했습니다. 자세한 내용은 Distributed Map 상태의 허용 실패 임계값 섹션을 참조하세요.

States.HeartbeatTimeout

Task 상태에서 HeartbeatSeconds 값보다 오랜 시간 동안 하트비트를 보내지 못했습니다.

참고

이 오류는 CatchRetry 필드 내에서만 나타납니다.

States.IntrinsicFailure

페이로드 템플릿 내에서 내장 함수를 간접적으로 호출하려는 시도가 실패했습니다.

States.ItemReaderFailed

ItemReader 필드에 지정된 항목 소스에서 Map 상태를 읽을 수 없으므로 이 상태가 실패했습니다. 자세한 내용은 ItemReader 섹션을 참조하세요.

States.NoChoiceMatched

Choice 상태에서 선택 규칙에 정의된 조건과 입력을 일치시키지 못했고 기본 전환이 지정되지 않았습니다.

States.ParameterPathFailure

경로를 사용하여 상태 Parameters 필드 내에서 이름이 .$로 끝나는 필드를 교체하려는 시도가 실패했습니다.

States.Permissions

지정된 코드를 실행할 수 있는 권한이 부족하여 Task 상태가 실패했습니다.

States.ResultPathMatchFailure

Step Functions가 상태 ResultPath 필드를 상태에서 수신한 입력에 적용하지 못했습니다.

States.ResultWriterFailed

ResultWriter 필드에 지정된 대상에 결과를 쓸 수 없으므로 Map 상태가 실패했습니다. 자세한 내용은 ResultWriter 섹션을 참조하세요.

States.Runtime

처리할 수 없는 일부 예외로 인해 실행이 실패했습니다. 이러한 문제는 런타임 시 null JSON 페이로드에 InputPath 또는 OutputPath의 적용을 시도하는 등의 오류로 발생하는 경우가 많습니다. States.Runtime 오류를 검색할 수 없으며 이 오류로 인해 실행이 항상 실패합니다. States.ALL에서 Retry 또는 Catch를 사용해도 States.Runtime 오류를 포착하지 못합니다.

States.TaskFailed

실행 중에 Task 상태에 오류가 발생했습니다. Retry 또는 Catch에서 사용될 때 States.TaskFailedStates.Timeout을 제외한 모든 알려진 오류 이름과 일치하는 와일드카드 역할을 합니다.

States.Timeout

Task 상태가 TimeoutSeconds 값보다 오랜 시간을 실행했거나 HeartbeatSeconds 값보다 오랜 시간 동안 하트비트를 보내지 못했습니다.

또한 상태 시스템이 지정된 TimeoutSeconds 값보다 오래 실행되면 실행이 실패하고 States.Timeout 오류가 발생합니다.

상태는 다른 이름으로 오류를 보고할 수 있습니다. 하지만 이러한 오류 이름은 States. 접두사로 시작할 수 없습니다.

가장 좋은 방법은 프로덕션 코드가 AWS Lambda 서비스 예외 (Lambda.ServiceExceptionLambda.SdkClientException)를 처리하는지 확인하는 것입니다. 자세한 내용은 Lambda 서비스 예외 처리 섹션을 참조하세요.

참고

Lambda에서 처리되지 않은 오류는 오류 출력에서 Lambda.Unknown으로 보고됩니다. 메모리 부족 오류 및 함수 시간 초과도 여기에 포함됩니다. Lambda.Unknown, States.ALL 또는 States.TaskFailed를 일치시켜 이러한 오류를 처리할 수 있습니다. Lambda에서 최대 간접 호출 수에 도달하면 오류는 Lambda.TooManyRequestsException입니다. Lambda 함수 오류에 대한 자세한 내용은 AWS Lambda 개발자 안내서오류 처리 및 자동 재시도를 참조하세요.

오류 후 재시도

Task, ParallelMap 상태에 Retry라는 이름의 필드가 있을 수 있습니다. 이 필드의 값은 Retrier라고 알려진 객체의 배열이어야 합니다. 개별 Retrier는 특정 재시도 횟수를 나타내며, 보통 점점 시간 간격이 증가합니다.

이러한 상태 중 하나에서 오류를 보고하고 Retry 필드가 있으면 Step Functions에서 배열에 나열된 순서대로 Retire 전체를 스캔합니다. Retirer ErrorEquals 필드 값에 오류 이름이 나타나면 상태 시스템은 Retry 필드에 정의된 대로 재시도를 시도합니다.

redriven 실행에서 Retire가 정의된 작업, Parallel, 또는 Inline Map 상태를 다시 실행하면 redrive에 대한 최대 시도 횟수가 허용되도록 이러한 상태의 재시도 횟수가 0으로 재설정됩니다. redriven 실행의 경우 콘솔을 사용하여 이러한 상태의 개별 재시도를 추적할 수 있습니다. 자세한 내용은 실행 Redriving에서 redriven 실행 재시도 동작 섹션을 참조하세요.

Retrier에는 다음 필드가 포함됩니다.

참고

재시도는 상태 변환으로 취급됩니다. 상태 전환이 결제에 미치는 영향은 Step Functions 요금을 참조하세요.

ErrorEquals(필수)

오류 이름과 일치하는 문자열 배열(비어 있지 않음). 상태에서 오류를 보고하면 Step Functions는 Retrier 전체를 스캔합니다. 오류 이름이 이 어레이에 표시되면, 이 Retrier에 설명된 재시도 정책이 실행됩니다.

IntervalSeconds(선택 사항)

처음 재시도하기 전에 기다리는 시간(초)을 나타내는 정수입니다(기본값: 1). IntervalSeconds의 최대값은 99999999입니다.

MaxAttempts(선택 사항)

양수로, 최대 재시도 횟수를 나타냅니다(기본값 3). 지정된 횟수보다 많이 오류가 발생하는 경우 재시도가 중지되고 일반 오류 처리가 다시 시작됩니다. 값을 0으로 지정하면 오류가 결코 재시도되지 않습니다. MaxAttempts의 최대값은 99999999입니다.

BackoffRate(선택 사항)

각 재시도 후의 간격이 늘어나도록 IntervalSeconds에서 지정된 재시도 횟수를 곱하는 승수입니다. 기본적으로 BackoffRate 값은 2.0씩 증가합니다.

예를 들어 IntervalSeconds가 3, MaxAttempts가 3, BackoffRate가 2라고 가정해보겠습니다. 첫 번째 재시도는 오류가 발생한 지 3초 후에 수행됩니다. 두 번째 재시도는 첫 번째 재시도 후 6초 후에 수행됩니다. 반면 세 번째 재시도는 두 번째 재시도 후 12초 후에 수행됩니다.

MaxDelaySeconds(선택 사항)

재시도 간격을 최대로 늘릴 수 있는 최대값(초)을 설정하는 양의 정수입니다. 이 필드를 BackoffRate 필드와 함께 사용하면 유용합니다. 이 필드에 지정된 값은 각 연속 재시도에 적용되는 백오프 비율 승수로 인한 기하급수적 대기 시간을 제한합니다. MaxDelaySeconds에 0보다 크고 31622401보다 작은 값을 지정해야 합니다.

이 값을 지정하지 않으면 Step Functions는 재시도 간의 대기 시간을 제한하지 않습니다.

JitterStrategy(선택 사항)

연속 재시도 간의 대기 시간에 지터를 포함할지 여부를 결정하는 문자열입니다. 지터는 무작위 지연 간격으로 동시 재시도를 분산시켜 줄입니다. 이 문자열은 FULL 또는 NONE을 해당 값으로 수락합니다. 기본값은 NONE입니다.

예를 들어 MaxAttempts를 3으로, IntervalSeconds를 2로, BackoffRate를 2로 설정했다고 가정해 보겠습니다. 첫 번째 재시도는 오류가 발생한 지 2초 후에 수행됩니다. 두 번째 재시도는 첫 번째 재시도 후 4초 후에 수행되고 세 번째 재시도는 두 번째 재시도 후 8초 후에 수행됩니다. JitterStrategyFULL로 설정하면 첫 번째 재시도 간격은 0~2초 사이에서 무작위로, 두 번째 재시도 간격은 0~4초 사이에서 무작위로, 세 번째 재시도 간격은 0~8초 사이에서 무작위로 설정됩니다.

Retry 필드 예제

이 섹션에는 다음 Retry 필드 예제가 포함되어 있습니다.

작은 정보

오류 처리 워크플로 예제를 AWS 계정에 배포하려면 AWS Step Functions 워크숍오류 처리 모듈을 참조하세요.

예제 1 - BackoffRate를 사용하여 재시도

다음 예제의 Retry는 3초 동안 기다린 후 첫 번째 재시도를 두 번 수행합니다. 지정한 BackoffRate에 따라 Step Functions는 최대 재시도 횟수에 도달할 때까지 각 재시도 간의 간격을 늘립니다. 다음 예제에서는 첫 번째 재시도 후 3초 동안 기다린 후 두 번째 재시도가 시작합니다.

"Retry": [ { "ErrorEquals": [ "States.Timeout" ], "IntervalSeconds": 3, "MaxAttempts": 2, "BackoffRate": 1 } ]
예제 2 - MaxDelaySeconds를 사용하여 재시도

다음 예시에서는 재시도를 3번 수행하고 BackoffRate로 인한 대기 시간을 5초로 제한합니다. 첫 번째 재시도는 3초 동안 기다린 후에 수행됩니다. MaxDelaySeconds에서 설정한 최대 대기 시간 한도로 인해 두 번째 및 세 번째 재시도는 이전 재시도 후 5초 후에 수행됩니다.

"Retry": [ { "ErrorEquals": [ "States.Timeout" ], "IntervalSeconds": 3, "MaxAttempts": 3, "BackoffRate":2, "MaxDelaySeconds": 5, "JitterStrategy": "FULL" } ]

MaxDelaySeconds를 설정하지 않으면 두 번째 재시도는 첫 번째 재시도 후 6초 후에 수행되고 세 번째 재시도는 두 번째 재시도 후 12초 후에 수행됩니다.

예제 3 - States.Timeout을 제외한 모든 오류 재시도

Retrier의 ErrorEquals 필드에 표시되는 예약된 이름 States.ALL은 모든 오류 이름을 나타내는 와일드카드입니다. 이 이름은 ErrorEquals 어레이에 하나만 표시되어야 하며, Retry 어레이의 마지막 Retrier에 표시되어야 합니다. States.TaskFailed 이름은 와일드카드 역할도 하며 States.Timeout를 제외한 모든 오류와 일치합니다.

다음은 States.Timeout을 제외한 모든 오류를 재시도하는 Retry 필드의 예제입니다.

"Retry": [ { "ErrorEquals": [ "States.Timeout" ], "MaxAttempts": 0 }, { "ErrorEquals": [ "States.ALL" ] } ]
예제 4 — 복잡한 재시도 시나리오

Retrier의 파라미터는 단일 상태 실행의 맥락에서 해당 Retrier에 대한 모든 방문에 적용됩니다.

다음 Task 상태를 고려하십시오.

"X": { "Type": "Task", "Resource": "arn:aws:states:us-east-1:123456789012:task:X", "Next": "Y", "Retry": [ { "ErrorEquals": [ "ErrorA", "ErrorB" ], "IntervalSeconds": 1, "BackoffRate": 2.0, "MaxAttempts": 2 }, { "ErrorEquals": [ "ErrorC" ], "IntervalSeconds": 5 } ], "Catch": [ { "ErrorEquals": [ "States.ALL" ], "Next": "Z" } ] }

이 작업은 연속 4번 실패하며 오류 이름 ErrorA, ErrorB, ErrorCErrorB가 출력됩니다. 결과로 다음이 발생합니다.

  • 첫 번째 오류 2개는 첫 번째 Retrier와 일치하며 이로 인해 1초 및 2초 동안 대기합니다.

  • 세 번째 오류는 두 번째 Retrier와 일치하며 이로 인해 5초 동안 대기합니다.

  • 네 번째 오류는 첫 번째 Retrier와 일치합니다. 하지만 해당 특정 오류에 대한 최대 재시도 횟수 2회(MaxAttempts)에 이미 도달했습니다. 따라서 해당 Retrier가 실패하고 실행은 Catch 필드를 통해 워크플로를 Z 상태로 리디렉션합니다.

폴백 상태

Task, MapParallel 상태 각각에는 Catch라는 필드가 있을 수 있습니다. 이 필드의 값은 catchers라는 객체의 어레이이어야 합니다.

Catcher에는 다음 필드가 포함됩니다.

ErrorEquals(필수)

오류 이름에 연결되는 문자열 배열(비어 있지 않음)로, 동일한 이름의 Retrier 필드와 동일하게 지정됩니다.

Next(필수)

상태 머신의 상태 이름 중 하나와 정확히 일치하는 문자열입니다.

ResultPath(선택 사항)

Catcher에서 Next 필드에 지정된 상태로 전송하는 입력을 결정하는 경로입니다.

상태에서 오류를 보고하고 Retry 필드가 없거나 재시도를 통해 오류가 해결되지 않으면 Step Function는 배열에 나열된 순서대로 Catcher 전체를 스캔합니다. Catcher의 ErrorEquals 필드 값에 오류 이름이 표시되면 상태 머신이 Next 필드에 이름이 지정된 상태로 전환됩니다.

Catcher의 ErrorEquals 필드에 표시되는 예약된 이름 States.ALL은 모든 오류 이름을 나타내는 와일드카드입니다. 이 이름은 ErrorEquals 어레이에 하나만 표시되어야 하며, Catch 어레이의 마지막 Catcher에 표시되어야 합니다. States.TaskFailed 이름은 와일드카드 역할도 하며 States.Timeout를 제외한 모든 오류와 일치합니다.

다음은 Lambda 함수에서 처리되지 않은 Java 예외를 출력하면 RecoveryState 상태로 전환되는 Catch 필드의 예제입니다. 그렇지 않으면 필드가 다음과 같이 EndState 상태로 전환됩니다.

"Catch": [ { "ErrorEquals": [ "java.lang.Exception" ], "ResultPath": "$.error-info", "Next": "RecoveryState" }, { "ErrorEquals": [ "States.ALL" ], "Next": "EndState" } ]
참고

각 Catcher는 처리할 오류를 여러 개 지정할 수 있습니다.

오류 출력

Step Functions가 catch 이름에 지정된 상태로 전환되면 객체에는 일반적으로 Cause 필드가 포함됩니다. 이 필드 값은 육안으로 읽을 수 있는 오류 설명입니다. 이 객체를 오류 출력이라고 합니다.

예 예에서 첫 번째 Catcher에는 ResultPath 필드가 들어 있습니다. 이 예는 상태의 최상위에 있는 ResultPath 필드와 유사하게 작동하여 다음과 같은 두 가지 작업을 수행할 수 있습니다.

  • 상태 실행 결과를 가져와 상태 입력 전체 또는 일부분을 덮어씁니다.

  • 결과를 가져와 입력에 추가합니다. Catcher에서 오류를 처리하는 경우 상태 실행 결과가 오류 출력이 됩니다.

따라서 이 예제의 첫 번째 Catcher의 경우 입력에 error-info 필드가 아직 없으면 Catcher에서 오류 출력을 이 필드로 입력에 추가합니다. 그러면 Catcher가 전체 입력을 RecoveryState로 전송합니다. 두 번째 Catcher의 경우 오류 출력이 입력을 덮어쓰고 Catcher는 오류 출력만 EndState에 전송합니다.

참고

ResultPath 필드를 지정하지 않으면, 기본값이 $로 설정되며 전체 입력을 선택하여 덮어씁니다.

상태에 RetryCatch 필드가 모두 있으면 Step Functions는 적절한 Retrier를 먼저 사용합니다. 재시도 정책에서 오류를 해결하지 못하면 Step Functions는 일치하는 Catcher 전환을 적용합니다.

페이로드 및 서비스 통합으로 인한 오류

Catcher는 문자열 페이로드를 출력으로 반환합니다. Amazon Athena 또는 AWS CodeBuild와 같은 서비스 통합을 사용하는 경우 Cause 문자열을 JSON으로 변환할 수 있습니다. 다음은 내장 함수가 있는 Pass 상태에서 Cause 문자열을 JSON으로 변환하는 방법을 보여주는 예제입니다.

"Handle escaped JSON with JSONtoString": { "Type": "Pass", "Parameters": { "Cause.$": "States.StringToJson($.Cause)" }, "Next": "Pass State with Pass Processing" },

Retry 및 Catch를 사용하는 상태 시스템 예제

다음 예제에 정의된 상태 시스템에는 Lambda 함수가 2개 있습니다. 하나는 항상 실패하는 함수이고 다른 하나는 상태 시스템에 정의된 시간 제한이 발생할 수 있도록 충분히 오래 기다리는 함수입니다.

다음은 항상 실패하는 Node.js Lambda 함수 정의로, error 메시지를 반환합니다. 다음 상태 시스템 예제에서 이 Lambda 함수 이름은 FailFunction입니다. Lambda 함수를 만드는 방법은 1단계: Lambda 함수 생성 섹션을 참조하세요.

exports.handler = (event, context, callback) => { callback("error"); };

다음은 10초 동안 대기하는 Node.js Lambda 함수 정의입니다. 다음 상태 시스템 예제에서 이 Lambda 함수 이름은 sleep10입니다.

참고

Lambda 콘솔에서 이 Lambda 함수를 만들 때 고급 설정 섹션의 제한 시간 값을 3초(기본값)에서 11초로 변경해야 합니다.

exports.handler = (event, context, callback) => { setTimeout(function(){ }, 11000); };

Retry를 사용하여 실패 처리

이 상태 머신은 Retry 필드를 사용하여 실패하고 오류 이름 HandledError를 출력하는 함수를 재시도합니다. 재시도 간 지수 백오프를 사용하여 이 함수를 두 번 재시도합니다.

{ "Comment": "A Hello World example of the Amazon States Language using an AWS Lambda function", "StartAt": "HelloWorld", "States": { "HelloWorld": { "Type": "Task", "Resource": "arn:aws:lambda:us-east-1:123456789012:function:FailFunction", "Retry": [ { "ErrorEquals": ["HandledError"], "IntervalSeconds": 1, "MaxAttempts": 2, "BackoffRate": 2.0 } ], "End": true } } }

이 변형에서는 사전 정의된 오류 코드 States.TaskFailed를 사용하며 이 오류 코드는 Lambda 함수에서 출력하는 오류와 일치합니다.

{ "Comment": "A Hello World example of the Amazon States Language using an AWS Lambda function", "StartAt": "HelloWorld", "States": { "HelloWorld": { "Type": "Task", "Resource": "arn:aws:lambda:us-east-1:123456789012:function:FailFunction", "Retry": [ { "ErrorEquals": ["States.TaskFailed"], "IntervalSeconds": 1, "MaxAttempts": 2, "BackoffRate": 2.0 } ], "End": true } } }
참고

모범 사례로서, Lambda 함수를 참조하는 작업이 Lambda 서비스 예외를 처리해야 합니다. 자세한 내용은 Lambda 서비스 예외 처리 섹션을 참조하세요.

Catch를 사용하여 실패 처리

이 예제에서는 Catch 필드를 사용합니다. Lambda 함수에서 오류를 출력하면 오류가 포착되고 상태 시스템이 fallback 상태로 전환됩니다.

{ "Comment": "A Hello World example of the Amazon States Language using an AWS Lambda function", "StartAt": "HelloWorld", "States": { "HelloWorld": { "Type": "Task", "Resource": "arn:aws:lambda:us-east-1:123456789012:function:FailFunction", "Catch": [ { "ErrorEquals": ["HandledError"], "Next": "fallback" } ], "End": true }, "fallback": { "Type": "Pass", "Result": "Hello, AWS Step Functions!", "End": true } } }

이 변형에서는 사전 정의된 오류 코드 States.TaskFailed를 사용하며 이 오류 코드는 Lambda 함수에서 출력하는 오류와 일치합니다.

{ "Comment": "A Hello World example of the Amazon States Language using an AWS Lambda function", "StartAt": "HelloWorld", "States": { "HelloWorld": { "Type": "Task", "Resource": "arn:aws:lambda:us-east-1:123456789012:function:FailFunction", "Catch": [ { "ErrorEquals": ["States.TaskFailed"], "Next": "fallback" } ], "End": true }, "fallback": { "Type": "Pass", "Result": "Hello, AWS Step Functions!", "End": true } } }

Retry를 사용하여 제한 시간 처리

이 상태 시스템은 Retry 필드를 사용하여 TimeoutSeconds에 지정된 제한 시간 값에 따라 제한 시간이 초과된 Task 상태를 재시도합니다. Step Functions는 이 Task 상태에서 Lambda 함수 간접 호출을 두 번 재시도하며 재시도 간에 지수 백오프를 적용합니다.

{ "Comment": "A Hello World example of the Amazon States Language using an AWS Lambda function", "StartAt": "HelloWorld", "States": { "HelloWorld": { "Type": "Task", "Resource": "arn:aws:lambda:us-east-1:123456789012:function:sleep10", "TimeoutSeconds": 2, "Retry": [ { "ErrorEquals": ["States.Timeout"], "IntervalSeconds": 1, "MaxAttempts": 2, "BackoffRate": 2.0 } ], "End": true } } }

Catch를 사용하여 제한 시간 처리

이 예제에서는 Catch 필드를 사용합니다. 시간 초과가 발생하면 상태 머신이 fallback 상태로 전환됩니다.

{ "Comment": "A Hello World example of the Amazon States Language using an AWS Lambda function", "StartAt": "HelloWorld", "States": { "HelloWorld": { "Type": "Task", "Resource": "arn:aws:lambda:us-east-1:123456789012:function:sleep10", "TimeoutSeconds": 2, "Catch": [ { "ErrorEquals": ["States.Timeout"], "Next": "fallback" } ], "End": true }, "fallback": { "Type": "Pass", "Result": "Hello, AWS Step Functions!", "End": true } } }
참고

ResultPath를 사용하여 상태 입력과 오류를 저장할 수 있습니다. ResultPath a에 오류와 입력을 모두 포함하는 데 사용합니다. Catch을(를) 참조하세요.