Control de errores en 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:

• Problemas con la definición de la máquina de estado (por ejemplo, un estado Choice no tiene ninguna regla)

• Errores de tareas (por ejemplo, una excepción de una función de AWS Lambda)

• Problemas transitorios (por ejemplo, eventos relacionados con las particiones de red)

De forma predeterminada, cuando un estado registra un error, AWS Step Functions hace que la ejecución falle por completo.

sugerencia

Para implementar un ejemplo de flujo de trabajo que incluya control de errores en la Cuenta de AWS, consulte el Módulo 8: Control de errores de El workshop de AWS Step Functions.

Nombres de error

Step Functions identifica los errores en Amazon States Language mediante cadenas que distinguen entre mayúsculas y minúsculas, denominadas nombres de error. Amazon States Language define un conjunto de cadenas integradas que designan errores conocidos; todas comienzan por el prefijo States..

States.ALL

Comodín que coincide con cualquier nombre de error conocido.

nota

Este tipo de error no puede detectar el tipo de error de terminal de States.DataLimitExceeded ni los tipos de error de tiempo de ejecución. Para obtener más información sobre estos tipos de error, consulte States.DataLimitExceeded y States.Runtime.

States.DataLimitExceeded

Step Functions informa de una excepción States.DataLimitExceeded en las condiciones siguientes:

• Cuando la salida de un conector supera la cuota de tamaño de carga útil.

• Cuando la salida de un estado supera la cuota de tamaño de la carga útil.

• Cuando, después del procesamiento de Parameters, la entrada de un estado es mayor que la cuota de tamaño de la carga útil.

Para obtener más información sobre cuotas, consulte Cuotas.

nota

Se trata de un error de terminal que el tipo de error States.ALL no puede detectar.

States.ExceedToleratedFailureThreshold

Se produjo un error en un estado Map porque el número de elementos con errores superó el umbral especificado en la definición de la máquina de estado. Para obtener más información, consulte Umbral de error tolerado para el estado Distributed Map.

States.HeartbeatTimeout

Estado Task que no puede enviar un latido durante un período mayor que el valor de HeartbeatSeconds.

nota

Este error solo está disponible dentro de los campos Catch y Retry.

States.IntrinsicFailure

Se produjo un error al intentar invocar una función intrínseca dentro de una plantilla de carga útil.

States.ItemReaderFailed

Se produjo un error en un estado Map porque no se pudo leer la fuente del elemento especificada en el campo ItemReader. Para obtener más información, consulte ItemReader.

States.NoChoiceMatched

Un estado Choice no pudo encontrar coincidencias entre la entrada y las condiciones definidas en la regla de elección y no se especificó una transición predeterminada.

States.ParameterPathFailure

Se produce un error al intentar reemplazar un campo dentro del campo Parameters de un estado cuyo nombre termina en .$ con una ruta.

States.Permissions

Un estado Task registró un error porque no tenía privilegios suficientes para ejecutar el código especificado.

States.ResultPathMatchFailure

Step Functions no pudo aplicar el campo ResultPath de un estado a la entrada que recibió el estado.

States.ResultWriterFailed

Un estado Map no pudo escribir los resultados en el destino especificado en el campo ResultWriter. Para obtener más información, consulte ResultWriter.

States.Runtime

Error de ejecución causado por una excepción que no se ha podido procesar. La causa de estos problemas suelen ser errores en el tiempo de ejecución, como intentar aplicar InputPath o OutputPath a una carga JSON nula. Un error States.Runtime no se puede volver a intentar y siempre provocará que se produzca un error en la ejecución. Un reintento o captura de States.ALL no capturará los errores de States.Runtime.

States.TaskFailed

Estado Task que registró un error durante la ejecución. Cuando se usa en un reintento o una captura, States.TaskFailed actúa como un comodín que coincide con cualquier nombre de error conocido excepto States.Timeout.

States.Timeout

Estado Task que se ejecuta durante más tiempo que el valor TimeoutSeconds o que no puede enviar un latido durante un período mayor que el valor de HeartbeatSeconds.

Además, si una máquina de estado funciona durante más tiempo que el valor TimeoutSeconds especificado, se produce un error States.Timeout en la ejecución.

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

Utilice la práctica recomendada de asegurarse de que el código de producción controle las excepciones del servicio de AWS Lambda (Lambda.ServiceException y Lambda.SdkClientException). Para obtener más información, consulte Gestionar excepciones de servicio de Lambda.

nota

Los errores no controlados en Lambda se notifican como Lambda.Unknown en el resultado del error. Estos incluyen los errores de memoria insuficiente y los tiempos de espera de funciones. Puede buscar coincidencias de estos errores con Lambda.Unknown, States.ALL o States.TaskFailed para controlarlos. Cuando Lambda alcanza el número máximo de invocaciones, el error es. Lambda.TooManyRequestsException Para obtener más información acerca de errores de función de Lambda, consulte Tratamiento de errores y reintentos automáticos en la Guía para desarrolladores de AWS Lambda.

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 Task, un Parallel 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 Redriving de ejecuciones.

Los reintentadores contienen los siguientes campos:

nota

Los reintentos se tratan como transiciones de estado. Para obtener información sobre cómo las transiciones de estado afectan a la facturación, consulte Precios de Step Functions.

ErrorEquals (Obligatorio)

Matriz no vacía de cadenas que coinciden con nombres de error. Cuando un estado registra un error, Step Functions lo analiza a través de los reintentadores. Cuando el nombre de error aparece en esta matriz, se implementa la política de reintentos que se describe en este reintentador.

IntervalSeconds (opcional)

Entero positivo que representa el número de segundos antes del primer reintento (el valor predeterminado es 1). El valor máximo de IntervalSeconds es 99999999.

MaxAttempts (opcional)

Entero positivo que representa el número máximo de reintentos (el valor predeterminado es 3). Si el error se repite más veces de las especificadas, se interrumpen los reintentos y se reanuda el control normal de errores. Un valor de 0 especifica que el error nunca se volverá a intentar. El valor máximo de MaxAttempts es 99999999.

BackoffRate (opcional)

Multiplicador según el cual aumenta el intervalo de reintento que indica IntervalSeconds después de cada intento de reintento. De forma predeterminada, el BackoffRate valor aumenta en 2.0.

Por ejemplo, supongamos que IntervalSeconds es 3, MaxAttempts es 3 y BackoffRate es 2. El primer intento se realiza tres segundos después de que se produzca el error. El segundo reintento tiene lugar seis segundos después del primer intento. El tercer reintento tiene lugar 12 segundos después del segundo reintento.

MaxDelaySeconds (opcional)

Un entero positivo que establece el valor máximo, en segundos, hasta el que puede aumentar un intervalo de reintento. Es útil utilizar este campo con el campo BackoffRate. El valor que se especifica en este campo limita los tiempos de espera exponenciales resultantes del multiplicador de la tasa de regresión que se aplique a cada reintento consecutivo. Debe especificar un valor mayor que 0 y menor que 31622401 para MaxDelaySeconds.

Si no especifica este valor, Step Functions no limitará los tiempos de espera entre reintentos.

JitterStrategy (opcional)

Cadena que determina si se debe incluir o no la fluctuación en los tiempos de espera entre reintentos consecutivos. La fluctuación reduce los reintentos simultáneos al distribuirlos en un intervalo de retardo aleatorio. Esta cadena acepta FULL o NONE como valores. El valor predeterminado es NONE.

Por ejemplo, supongamos que ha establecido MaxAttempts como 3, IntervalSeconds como 2 y BackoffRate como 2. El primer intento se realiza dos segundos después de que se produzca el error. El segundo reintento tiene lugar cuatro segundos después del primer intento y el tercer reintento, ocho segundos después del segundo intento. Si se establece JitterStrategy como FULL, el primer intervalo de reintento se distribuye aleatoriamente entre 0 y 2 segundos, el segundo intervalo de reintento se distribuye aleatoriamente entre 0 y 4 segundos y el tercer intervalo de reintento se distribuye aleatoriamente entre 0 y 8 segundos.

Ejemplos de campo de reintento

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

• Retry with BackoffRate

• Retry with MaxDelaySeconds

• Retry all errors except States.Timeout

• Complex retry scenario

sugerencia

Para implementar un ejemplo de un flujo de trabajo de gestión de errores en la Cuenta de AWS, consulte el módulo Control de errores de El workshop de AWS Step Functions.

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

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

• Los dos primeros errores coinciden con el primer reintentador y generan esperas de uno y dos segundos.

• El tercer error coincide con el segundo reintentador y genera una espera de cinco segundos.

• El cuarto error también coincide con el primer reintentador. Sin embargo, ya alcanzó su máximo de dos reintentos (MaxAttempts) para ese error en particular. Por lo tanto, ese recuperador falla y la ejecución redirige el flujo de trabajo al estado Z a través del campo Catch.

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.

ErrorEquals (Obligatorio)

Matriz no vacía de cadenas que coinciden con nombres de error, especificados exactamente como se indicaron en el campo del mismo nombre del reintentador.

Next (Obligatorio)

Cadena que debe coincidir exactamente con uno de los nombres de estado de la máquina de estado.

ResultPath (opcional)

Ruta que determina qué entrada envía el receptor al estado especificado en el campo Next.

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

nota

Cada receptor puede especificar varios errores que deben controlarse.

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 este ejemplo, 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:

• Toma los resultados de la ejecución de ese estado y los sobrescribe todos los datos de entrada del estado o parte de ellos.

• Toma los resultados y los agrega a los datos de entrada. En el caso de los errores controlados por un receptor, el resultado de la ejecución del estado es la salida de error.

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.

nota

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.

nota

Cuando cree esta función de Lambda en la consola de Lambda, no olvide cambiar el valor de Tiempo de espera en la sección Configuración avanzada de 3 segundos (valor predeterminado) a 11 segundos.

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

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

nota

Es recomendable que las tareas que hacen referencia a una función de Lambda controlen las excepciones del servicio de Lambda. Para obtener más información, consulte Gestionar excepciones de servicio de Lambda.

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

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

Control de tiempos de espera con Retry

Esta máquina de estados 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": "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
      }
   }
}

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

nota

Puede conservar la entrada del estado y el error utilizando ResultPath. Consulte Se utiliza ResultPath para incluir tanto el error como la entrada en un Catch.