Tratar erros em fluxos de trabalho do Step Functions

Todos os estados, exceto Pass e Wait, podem encontrar erros de tempo de execução. Erros podem ocorrer por vários motivos, incluindo os seguintes:

Quando um estado relata um erro, o Step Functions por padrão causa falha na execução inteira da máquina de estado. O Step Functions também tem recursos mais avançados de tratamento de erros. Você pode configurar sua máquina de estado para capturar erros, repetir estados com falha e implementar protocolos de tratamento de erros com facilidade.

Os agentes de captura do Step Functions estão disponíveis para os estados tarefa, paralelo e mapa, mas não para falhas de execução de máquinas de estado de alto nível. Para lidar com as execuções que você prevê que possam falhar, o agente de captura pode tratar o erro ou você pode agrupar essas execuções em fluxos de trabalho secundários para detectar erros no fluxo de trabalho principal. Como alternativa, você pode optar por ouvir os eventos TIMED_OUT dos fluxos de trabalho padrão com um barramento do EventBridge e invocar uma ação para lidar com a falha na execução.

Nomes de erro

O Step Functions identifica erros usando strings que diferenciam maiúsculas e minúsculas, conhecidos como nomes de erro. A Amazon States Language define um conjunto de strings integradas que nomeiam erros conhecidos, todos iniciados com o prefixo States.

Os estados podem relatar erros com outros nomes. No entanto, os nomes de erro não podem começar com o prefixo States..

Verifique se o seu código de produção pode lidar com exceções de serviço do AWS Lambda (Lambda.ServiceException e Lambda.SdkClientException). Para obter mais informações, consulte como Processar exceções transitórias do serviço Lambda nas práticas recomendadas.

Repetir após um erro

Os estados Task, Parallel e Map podem ter um campo denominado Retry, cujo valor deve ser uma matriz de objetos conhecidos como agentes de repetição. Um agente de repetição individual representa determinado número de novas tentativas, geralmente em intervalos de tempo crescentes.

Quando um desses estados relata um erro e há um campo Retry, o Step Functions examina os agentes de repetição na ordem listada na matriz. Quando o nome do erro aparece no valor do campo ErrorEquals de um agente de repetição, a máquina de estado faz repetições, conforme definido no campo Retry.

Se a execução de redriven executar novamente Estado de tarefa do fluxo de trabalho, Estado paralelo do fluxo de trabalho ou um estado de mapa em linha, para o qual você tenha definido repetições, a contagem de repetições para esses estados será redefinida como 0 para possibilitar o número máximo de tentativas em redrive. Para uma execução redriven, você pode monitorar tentativas individuais desses estados usando o console. Para obter mais informações, consulte Repetir o comportamento das execuções redriven em Reiniciar as execuções da máquina de estado com redrive no Step Functions.

Um retrier contém os seguintes campos:

Exemplos de campo de repetição

Esta seção inclui os exemplos de campo Retry a seguir.

Exemplo 1: repetir com BackoffRate

O exemplo a seguir de uma Retry faz duas tentativas de repetição. A primeira ocorre depois de uma espera de três segundos. Com base na BackoffRate especificada, o Step Functions aumenta o intervalo entre cada repetição até que o número máximo de tentativas de repetição seja atingido. No exemplo a seguir, a segunda tentativa começa depois de uma espera de três segundos após a primeira repetição.

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

Exemplo 2: repetir com MaxDelaySeconds

O exemplo a seguir faz três tentativas de repetição e limita o tempo de espera resultante de BackoffRate em 5 segundos. A primeira repetição ocorre depois de uma espera de três segundos. A segunda e a terceira tentativas de repetição ocorrem após uma espera de cinco segundos após a tentativa de repetição anterior, devido ao limite máximo de tempo de espera definido por MaxDelaySeconds.

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

Sem MaxDelaySeconds, a segunda tentativa ocorreria seis segundos após a primeira tentativa, e a terceira ocorreria 12 segundos após a segunda tentativa.

Exemplo 3: repetir todos os erros, exceto States.Timeout

O nome reservado States.ALL que aparece no campo ErrorEquals de um retrier é um curinga que corresponde a qualquer nome de erro. Ele deve aparecer sozinho na matriz ErrorEquals e também no último retrier na matriz Retry. O nome States.TaskFailed também atua como um curinga e corresponde a qualquer erro, exceto States.Timeout.

O exemplo de campo Retry a seguir repete qualquer erro, exceto States.Timeout.

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

Exemplo 4: cenário complexo de repetição

Parâmetros de um retrier em todas as visitas ao retrier no contexto de uma única execução de estado.

Considere o seguinte estado Task.

"X": {
   "Type": "Task",
   "Resource": "arn:aws:states:region: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"
   } ]
}

Essa tarefa falha quatro vezes sucessivas, produzindo estes nomes de erro: ErrorA, ErrorB, ErrorC e ErrorB. O seguinte ocorre em consequência disso:

Estados de fallback

Os estados Task, Map e Parallel podem ter um campo denominado Catch. O valor desse campo deve ser uma matriz de objetos, conhecidos como catchers.

Um catcher contém os campos a seguir.

Quando um estado relata um erro e não existe nenhum campo Retry ou as repetições não conseguem resolver o erro, o Step Functions examina os coletores na ordem listada na matriz. Quando o nome do erro é exibido no valor do campo ErrorEquals de um catcher, a máquina de estado muda para o estado denominado no campo Next.

O nome reservado States.ALL que aparece em um campo ErrorEquals do catcher é um curinga que corresponde a qualquer nome de erro. Ele deve aparecer sozinho na matriz ErrorEquals e também no último catcher na matriz Catch. O nome States.TaskFailed também atua como um curinga e corresponde a qualquer erro, exceto States.Timeout.

O exemplo a seguir de um campo Catch muda para o estado denominado RecoveryState quando uma função do Lambda gera uma exceção Java não tratada. Do contrário, o campo muda para o estado EndState.

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

Error output (Saída de erro)

Quando o Step Functions muda para o estado especificado em um nome de captura, o objeto normalmente contém o campo Cause. O valor desse campo é uma descrição de erro humanamente. Esse objeto é conhecido como saída de erro.

No exemplo anterior do JSONPath, o primeiro agente de captura contém um campo ResultPath. Ele funciona de modo semelhante a um campo ResultPath em um nível superior do estado, o que resulta em duas possibilidades:

Portanto, no exemplo, o primeiro agente de captura adiciona a saída de erro à entrada como um campo chamado error-info caso ainda não haja um campo com esse nome na entrada. Depois, o agente de captura envia toda a entrada a RecoveryState. Em relação ao segundo agente de captura, a saída de erro substitui a entrada e o agente de captura só envia a saída de erro a EndState.

Em fluxos de trabalho JSONPath, se você não especificar o campo ResultPath, ele usará $ como padrão, que seleciona e substitui a entrada completa.

Quando um estado tem os campos Retry e Catch, o Step Functions usa primeiro qualquer agente de repetição apropriado. Se a política de repetição não solucionar o erro, o Step Functions aplicará a transição correspondente do agente de captura.

Causar cargas úteis e integrações de serviços

Um agente de captura exibe uma carga útil de string como saída. Ao trabalhar com integrações de serviços, como Amazon Athena ou AWS CodeBuild, talvez você queira converter a string Cause em JSON. O exemplo a seguir de um estado Pass com funções intrínsecas mostra como converter uma string Cause em JSON.

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

Exemplos de máquina de estado usando repetição e captura

As máquinas de estado definidas nos exemplos a seguir presumem que existem duas funções do Lambda: uma que sempre falha e uma que aguarda tempo suficiente para permitir que haja um tempo limite definido na máquina de estado.

Essa é uma definição de função do Lambda Node.js que sempre falha, retornando a mensagem error. Nos exemplos de máquina de estado a seguir, essa função do Lambda é denominada FailFunction. Para ter mais informações sobre como criar uma função do Lambda, consulte a seção Etapa 1: criar uma função do Lambda.

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

Essa é uma definição de função do Lambda Node.Js que permanece desativada por dez segundos. Nos exemplos de máquina de estado a seguir, essa função do Lambda é denominada sleep10.

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

Tratar uma falha usando repetição

Essa máquina de estado usa um campo Retry para tentar novamente uma função que falha e gera o nome de erro HandledError. Ela repete essa função duas vezes com um recuo exponencial entre as repetições.

{
   "Comment": "A Hello World example invoking Lambda function",
   "StartAt": "HelloWorld",
   "States": {
      "HelloWorld": {
         "Type": "Task",
         "Resource": "arn:aws:lambda:region:123456789012:function:FailFunction",
         "Retry": [ {
            "ErrorEquals": ["HandledError"],
            "IntervalSeconds": 1,
            "MaxAttempts": 2,
            "BackoffRate": 2.0
         } ],
      "End": true
      }
   }
}

Essa variante usa o código de erro predefinido States.TaskFailed, que corresponde a qualquer erro gerado por uma função do Lambda.

{
   "Comment": "Hello World example which invokes a AWS Lambda function",
   "StartAt": "HelloWorld",
   "States": {
      "HelloWorld": {
         "Type": "Task",
         "Resource": "arn:aws:lambda:region:123456789012:function:FailFunction",
         "Retry": [ {
            "ErrorEquals": ["States.TaskFailed"],
            "IntervalSeconds": 1,
            "MaxAttempts": 2,
            "BackoffRate": 2.0
         } ],
         "End": true
      }
   }
}

Tratar uma falha usando captura

Este exemplo usa um campo Catch. Quando uma função do Lambda gera um erro, ele é detectado e a máquina de estado muda para o estado fallback.

{
   "Comment": "Hello World example which invokes a AWS Lambda function",
   "StartAt": "HelloWorld",
   "States": {
      "HelloWorld": {
         "Type": "Task",
         "Resource": "arn:aws:lambda:region:123456789012:function:FailFunction",
         "Catch": [ {
            "ErrorEquals": ["HandledError"],
            "Next": "fallback"
         } ],
         "End": true
      },
      "fallback": {
         "Type": "Pass",
         "Result": "Hello, AWS Step Functions!",
         "End": true
      }
   }
}

Essa variante usa o código de erro predefinido States.TaskFailed, que corresponde a qualquer erro gerado por uma função do Lambda.

{
   "Comment": "Hello World example which invokes a AWS Lambda function",
   "StartAt": "HelloWorld",
   "States": {
      "HelloWorld": {
         "Type": "Task",
         "Resource": "arn:aws:lambda:region:123456789012:function:FailFunction",
         "Catch": [ {
            "ErrorEquals": ["States.TaskFailed"],
            "Next": "fallback"
         } ],
      "End": true
      },
      "fallback": {
         "Type": "Pass",
         "Result": "Hello, AWS Step Functions!",
         "End": true
      }
   }
}

Tratar um tempo limite usando repetição

Essa máquina de estado usa um campo Retry para repetir um estado Task que atinge o tempo limite, com base no valor de tempo limite especificado em TimeoutSeconds. O Step Functions repete a invocação da função do Lambda nesse estado Task duas outras vezes, com recuo exponencial entre as repetições.

{
   "Comment": "Hello World example which invokes a AWS Lambda function",
   "StartAt": "HelloWorld",
   "States": {
      "HelloWorld": {
         "Type": "Task",
         "Resource": "arn:aws:lambda:region:123456789012:function:sleep10",
         "TimeoutSeconds": 2,
         "Retry": [ {
            "ErrorEquals": ["States.Timeout"],
            "IntervalSeconds": 1,
            "MaxAttempts": 2,
            "BackoffRate": 2.0
         } ],
         "End": true
      }
   }
}

Tratar um tempo limite usando captura

Este exemplo usa um campo Catch. Quando ocorre um tempo limite, a máquina de estado muda para o estado fallback.

{
   "Comment": "Hello World example which invokes a AWS Lambda function",
   "StartAt": "HelloWorld",
   "States": {
      "HelloWorld": {
         "Type": "Task",
         "Resource": "arn:aws:lambda:region:123456789012:function:sleep10",
         "TimeoutSeconds": 2,
         "Catch": [ {
            "ErrorEquals": ["States.Timeout"],
            "Next": "fallback"
         } ],
         "End": true
      },
      "fallback": {
         "Type": "Pass",
         "Result": "Hello, AWS Step Functions!",
         "End": true
      }
   }
}