Step Functions 오류 처리 - AWS Step Functions

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

Step Functions 오류 처리

어떤 상태에서든 런타임 오류가 발생할 수 있습니다. 오류는 다음과 같은 다양한 이유로 발생할 수 있습니다.

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

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

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

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

오류 처리 예제를AWS 계정 배포하려면 모듈 8 -AWS Step Functions 워크숍의 오류 처리를 참조하십시오.

오류 이름

Step Functions Functions는 오류 이름이라고 하는 대소문자를 구분하는 문자열을 사용하여 Amazon States Language의 오류를 식별합니다. Amazon States 언어는 잘 알려진 오류의 이름을 지정하는 내장 문자열 세트를 정의하며, 모두States. 접두사로 시작합니다.

States.ALL

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

참고

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

States.BranchFailed

Parallel 국가의 한 지부가 실패했습니다.

States.DataLimitExceeded

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

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

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

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

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

참고

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

States.ExceedToleratedFailureThreshold

실패한 항목 수가Map 상태 컴퓨터 정의에 지정된 임계값을 초과했기 때문에 상태가 실패했습니다. 자세한 정보는 맵 상태에 대한 허용 장애 임계값을 참조하세요.

States.HeartbeatTimeout

Task상태가HeartbeatSeconds 값보다 긴 기간 동안 하트비트를 전송하지 못했습니다.

참고

이 오류는CatchRetry 필드 내에서만 사용할 수 있습니다.

States.IntrinsicFailure

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

States.ItemReaderFailed

ItemReader필드에 지정된 항목 소스에서 읽을 수 없어서Map 상태가 실패했습니다. 자세한 정보는 ItemReader을 참조하세요.

States.NoChoiceMatched

Choice상태가 Choice Rule에 정의된 조건과 입력을 일치시키지 못했고 Default 전환이 지정되지 않았습니다.

States.ParameterPathFailure

상태 필드 내에서 이름이 경로.$ 사용으로 끝나는Parameters 필드를 바꾸려는 시도는 실패합니다.

States.Permissions

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

States.ResultPathMatchFailure

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

States.ResultWriterFailed

ResultWriter필드에 지정된 대상에 결과를 쓸 수 없어서Map 상태가 실패했습니다. 자세한 정보는 ResultWriter을 참조하세요.

States.Runtime

처리할 수 없는 일부 예외로 인해 실행이 실패했습니다. 이러한 문제는 런타임 시 null JSON 페이로드에 InputPath 또는 OutputPath의 적용을 시도하는 등의 오류로 발생하는 경우가 많습니다. States.Runtime오류는 복구할 수 없으며 항상 실행이 실패하게 됩니다. 다시 시도하거나States.ALL 캐치온해도States.Runtime 오류가 발견되지 않습니다.

States.TaskFailed

실행 중에 Task 상태에 오류가 발생했습니다. 재시도 또는 캐치에 사용될 경우 를 제외한 알려진 오류 이름과 일치하는 와일드카드States.TaskFailed 역할을States.Timeout 합니다.

States.Timeout

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

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

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

참고

Lambda에서 처리되지 않은 오류는 오류 출력과 같이Lambda.Unknown 보고됩니다. 여기에는 out-of-memory 오류 및 함수 타임아웃이 포함됩니다. Lambda.Unknown, States.ALL 또는 States.TaskFailed를 일치시켜 이러한 오류를 처리할 수 있습니다. Lambda가 최대 호출 수에 도달하면 오류가 발생합니다Lambda.TooManyRequestsException. Lambda 함수 오류에 대한 자세한 내용은 AWS Lambda개발자 안내서의 오류 처리 및 자동 재시도를 참조하십시오.

오류 발생 후 재시도

TaskParallel 상태에 Retry라는 이름의 필드가 있을 수 있습니다. 이 필드의 값은 retriers라는 객체의 어레이여야 합니다. 개별 Retrier는 특정 재시도 횟수를 나타내며, 보통 점점 시간 간격이 증가합니다.

참고

재시도는 상태 변환으로 취급됩니다. 상태 전환이 결제에 미치는 영향에 대한 자세한 내용은 Step Functions 가격 책정을 참조하십시오.

리트리어는 다음 필드를 포함합니다.

ErrorEquals (필수)

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

IntervalSeconds(선택 사항)

첫 번째 재시도 이전의 시간 (초) 을 나타내는 정수 (1기본값). IntervalSeconds의 최대값은99999999 입니다.

MaxAttempts(선택 사항)

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

BackoffRate(선택 사항)

로 표시된 재시도 간격이 재시도 시도할 때마다IntervalSeconds 증가하는 배수입니다. 기본적으로 값은 다음과BackoffRate 같이 증가합니다2.0.

다음 예에서는 3초 동안 기다린 후 첫 번째 재시도를 하고 첫 번째 재시도 후 3초 동안 기다린 후 두 번째 재시도를 두 번 시도하는 예제입니다.Retry 전체 예제를 보려면 의 stepfunction-error-handling-examples리포지토리를 참조하십시오 GitHub.

"Retry": [ { "ErrorEquals": [ "States.Timeout" ], "IntervalSeconds": 3, "MaxAttempts": 2, "BackoffRate": 1 } ]

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

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

"Retry": [ { "ErrorEquals": [ "States.Timeout" ], "MaxAttempts": 0 }, { "ErrorEquals": [ "States.ALL" ] } ]

복합 재시도 시나리오

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" } ] }

이 작업은 네 번 연속으로 실패하고,,ErrorAErrorBErrorC, 다음과 같은 오류 이름을ErrorB 출력합니다. 결과로 다음이 발생합니다.

  • 처음 두 오류는 첫 번째 리트리어와 일치하며 1~2초의 대기 시간이 발생합니다.

  • 세 번째 오류는 두 번째 리트리어와 일치하며 5초 동안 대기합니다.

  • 네 번째 오류는 첫 번째 리트리어와도 일치합니다. 그러나 해당 오류에 대해 이미 최대 두 번의 재시도 (MaxAttempts) 에 도달했습니다. 따라서 해당 리트리어는 실패하고 실행은Catch 필드를 통해 워크플로를Z 상태로 리디렉션합니다.

폴백 상태

TaskMapParallel 상태에는 각각 이름이 지정된 필드가 있을 수Catch 있습니다. 이 필드의 값은 catchers라는 객체의 어레이이어야 합니다.

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

ErrorEquals (필수)

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

Next (필수)

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

ResultPath(선택 사항)

Catcher가Next 필드에 지정된 상태로 보내는 입력을 결정하는 경로입니다.

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

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

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

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

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

오류 출력

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

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

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

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

따라서 예제의 첫 번째 Catcher의 경우 입력에 이 이름을 가진 필드가 아직 없는error-info 경우 Catcher는 오류 출력을 이름이 지정된 필드로 입력에 추가합니다. 그런 다음, 포수는 전체 입력을 로 보냅니다RecoveryState. 두 번째 캐처의 경우 오류 출력이 입력을 덮어쓰고 캐처는 오류 출력만 로 보냅니다EndState.

참고

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

상태에RetryCatch 필드가 모두 있는 경우 Step Functions는 적절한 리트리어를 먼저 사용합니다. 재시도 정책으로 오류가 해결되지 않는 경우 Step Functions Functions는 일치하는 캐처 전환을 적용합니다.

원인 페이로드 및 서비스 통합

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" },

재시도 사용 및 Catch 사용 예제

다음 예제에 정의된 상태 머신은 두 개의 Lambda 함수가 있다고 가정합니다. 하나는 항상 실패하고 다른 하나는 상태 머신에 정의된 시간 초과가 발생할 수 있을 만큼 충분히 오래 대기합니다.

이는 항상 실패하여 메시지를 반환하는 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 } } }

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

{ "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 } } }

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

{ "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 필드를 사용하여 에서 지정한 제한 시간 값에 따라 제한 시간이 초과된Task 상태를TimeoutSeconds 재시도합니다. Step Functions 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을 참조하세요.