Control de errores en los flujos de trabajo de Step Functions

Todos los estados, excepto los estados Pass y Wait, pueden encontrar errores de tiempo de ejecución. Los errores pueden ocurrir por varios motivos, como los siguientes:

Cuando un estado registra un error, Step Functions genera un error de forma predeterminada para toda la ejecución de la máquina de estado. Step Functions también cuenta con características de gestión de errores más avanzadas. Puede configurar su máquina de estado para detectar errores, reintentar los estados fallidos e implementar correctamente los protocolos de control de errores.

Los receptores de Step Functions están disponibles para los estados Task, Parallel y Map, pero no para los errores de ejecución de máquinas de estado de nivel superior. Para controlar las ejecuciones que prevé que podrían fallar, el iniciador puede gestionar el error o puede anidar esas ejecuciones dentro de flujos de trabajo secundarios para detectar errores dentro del flujo de trabajo principal. Como alternativa, puede optar por escuchar eventos TIMED_OUT desde los flujos de trabajo estándar con un bus de EventBridge e invocar una acción para gestionar la ejecución con error.

Nombres de error

Step Functions identifica errores utilizando cadenas que distinguen mayúsculas de minúsculas, lo que se conoce como nombres de error. Amazon States Language define un conjunto de cadenas integradas que designan errores conocidos; todas comienzan por el prefijo States..

Los estados pueden notificar errores con otros nombres. No obstante, los nombres de error no pueden empezar por el prefijo States.

Asegúrese de que el código de producción pueda controlar las excepciones del servicio de AWS Lambda (Lambda.ServiceException y Lambda.SdkClientException). Para obtener más información, consulte Gestionar excepciones transitorias del servicio de Lambda en Prácticas recomendadas.

Reintento después de un error

Los estados Task, Parallel y Map pueden tener un campo llamado Retry, cuyo valor debe ser una matriz de objetos denominados reintentadores. Cada reintentador representa un número determinado de reintentos, que normalmente aumentan en intervalos de tiempo.

Cuando uno de estos estados informa de un error y hay un campo Retry, Step Functions escanea los reintentadores en el orden indicado en la matriz. Cuando el nombre del error aparece en el valor del campo ErrorEquals de un reintentador, la máquina de estado realiza reintentos tal como se define en el campo Retry.

Si la ejecución de redriven se vuelve a realizar con un Estado de un flujo de trabajo de tarea, un Estado Parallel de un flujo de trabajo o un estado Map en línea para el que haya definido reintentos, el recuento de reintentos para estos estados se restablecerá en 0 para permitir el número máximo de intentos en redrive. Para una ejecución redriven, puede realizar un seguimiento de los reintentos individuales de estos estados mediante la consola. Para obtener más información, consulte Comportamiento de reintento de las ejecuciones redriven en Reinicio de ejecuciones de máquinas de estado con redrive en Step Functions.

Los reintentadores contienen los siguientes campos:

Ejemplos de campo de reintento

Esta sección incluye los siguientes ejemplos de código para Retry.

Ejemplo 1: Reintento con BackOffRate

En el siguiente ejemplo de Retry se realizan dos reintentos; el primero se realiza tras una espera de tres segundos. Según lo que especifique BackoffRate, Step Functions aumenta el intervalo entre cada reintento hasta alcanzar el número máximo de reintentos. En el ejemplo siguiente, el segundo reintento comienza después de esperar tres segundos tras el primer reintento.

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

Ejemplo 2: Reintento con MaxDelaySeconds

En el siguiente ejemplo, se realizan tres reintentos y se limita el tiempo de espera resultante de BackoffRate a 5 segundos. El primer reintento se realiza tras esperar tres segundos. El segundo y el tercer reintento se realizan después de esperar cinco segundos después del reintento anterior, debido al límite máximo de tiempo de espera establecido en MaxDelaySeconds.

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

Sin MaxDelaySeconds, el segundo reintento tendría lugar seis segundos después del primer reintento y el tercer reintento tendría lugar 12 segundos después del segundo.

Ejemplo 3: Reintentar todos los errores excepto States.Timeout

El nombre reservado States.ALL que aparece en el campo ErrorEquals de un reintentador es un nombre comodín que coincide con cualquier nombre de error. Debe aparecer solo en la matriz ErrorEquals y debe aparecer en el último reintentador de la matriz Retry. El nombre States.TaskFailed también actúa como comodín y coincide con cualquier error excepto con States.Timeout.

En el siguiente ejemplo de un campo Retry, se reintentan todos los errores excepto States.Timeout.

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

Ejemplo 4: Escenario de reintento complejo

Los parámetros de un reintentador se aplican a todas las visitas que se realizan a dicho reintentador durante la ejecución de un único estado.

Supongamos que tenemos el siguiente 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"
   } ]
}

Esta tarea falla cuatro veces seguidas y devuelve estos nombres de error: ErrorA, ErrorB, ErrorC y ErrorB. Como resultado, se produce lo siguiente:

Estados alternativos

Los estados Task, Map y Parallel pueden tener un campo llamado Catch. El valor de este campo debe ser una matriz de objetos, denominados receptores.

Un receptor contiene los siguientes campos.

Cuando un estado registra un error y no hay un campo Retry o los reintentos no son capaces de resolver el problema, Step Functions lo analiza a través de los receptores en el orden en que aparecen en la matriz. Cuando el nombre de error aparece en el valor del campo ErrorEquals de un receptor, la máquina de estado adopta el estado especificado en el campo Next.

El nombre reservado States.ALL que aparece en el campo ErrorEquals de un receptor es un nombre comodín que coincide con cualquier nombre de error. Debe aparecer solo en la matriz ErrorEquals y debe aparecer en el último receptor de la matriz Catch. El nombre States.TaskFailed también actúa como comodín y coincide con cualquier error excepto con States.Timeout.

En el siguiente ejemplo, el campo Catch cambia a un estado llamado RecoveryState cuando una función de Lambda genera una excepción Java no controlada. De lo contrario, el campo cambia al estado EndState.

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

Salida de error

Cuando Step Functions adopta el estado especificado en un nombre catch, por lo general, el objeto contiene el campo Cause. El valor de este campo es una descripción del error en lenguaje natural. Este objeto se conoce como salida de error.

En el ejemplo anterior de JSONPath, el primer receptor contiene un campo. ResultPath. Funciona de manera parecida a un campo ResultPath del nivel superior del estado, lo que genera dos posibilidades:

Por tanto, en el primer receptor del ejemplo, el receptor agrega la salida de error a la entrada como un campo llamado error-info si no hay ningún campo con este nombre en los datos de entrada. A continuación, el receptor envía la entrada completa a RecoveryState. En el segundo receptor, la salida de error sobrescribe la entrada y el receptor solo envía la salida de error a EndState.

Para flujos de trabajo de JSONPath, si no se especifica el campo ResultPath, este se establece de forma predeterminada en $, que selecciona y sobrescribe toda la entrada.

Cuando un estado tiene tanto campo Retry como Catch, Step Functions utiliza primero los recuperadores adecuados. Si la política de reintentos no resuelve el error, Step Functions aplica la transición del receptor correspondiente.

Provoca cargas útiles e integraciones de servicios

Un receptor devuelve una carga de cadenas como salida. Cuando trabaje con integraciones de servicios como Amazon Athena o AWS CodeBuild, puede que desee convertir la cadena Cause a JSON. El siguiente ejemplo de un estado Pass con funciones intrínsecas muestra cómo convertir una cadena Cause a JSON.

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

Ejemplos de máquina de estado que usan Retry y Catch

Las máquinas de estado que se definen en los ejemplos siguientes presuponen la existencia de dos funciones de Lambda: una que siempre registra errores y otra que espera lo suficiente para permitir que transcurra el tiempo de espera especificado en la máquina de estado.

Esta es una definición de una función de Lambda Node.js que nunca se ejecuta correctamente y devuelve el mensaje error. En los ejemplos de máquinas de estado siguientes, esta función de Lambda se llama FailFunction. Para obtener más información sobre la creación de una función de Lambda, consulte Paso 1: Crear una función de Lambda.

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

Esta es una definición de una función de Lambda Node.js que se suspende durante 10 segundos. En los ejemplos de máquinas de estado siguientes, esta función de Lambda se llama sleep10.

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

Control de errores con Retry

Esta máquina de estado utiliza un campo Retry para recuperar una función que no se ejecuta correctamente y que devuelve el nombre de error HandledError. La función se reintenta dos veces, con un retroceso exponencial entre los reintentos.

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

Esta variante utiliza el código de error predefinido States.TaskFailed, que coincide con cualquier error que una función de Lambda pueda devolver.

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

Control de errores con Catch

En este ejemplo se utiliza un campo Catch. Cuando una función de Lambda devuelve un error, se recibe el error y la máquina de estado adopta el 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
      }
   }
}

Esta variante utiliza el código de error predefinido States.TaskFailed, que coincide con cualquier error que una función de Lambda pueda devolver.

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

Control de tiempos de espera con Retry

Esta máquina de estado usa un campo Retry para reintentar un estado Task cuyo tiempo de espera se agota, en función del valor de tiempo de espera especificado en TimeoutSeconds. Step Functions vuelve a intentar la invocación de la función de Lambda en este estado Task dos veces, con un retroceso exponencial entre reintentos.

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

Control de tiempos de espera con Catch

En este ejemplo se utiliza un campo Catch. Cuando se agota un tiempo de espera, la maquina de estado adopta el 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
      }
   }
}