Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.
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 producirse por varios motivos, entre los que se incluyen los siguientes:
-
Problemas con la definición de la máquina de estados, como un estado de elección sin una regla coincidente
-
Fallos en las tareas, como una excepción en una AWS Lambda función
-
Problemas transitorios, como eventos de partición de red
Cuando un estado informa de un error, Step Functions falla de forma predeterminada toda la ejecución de la máquina de estados. Step Functions también cuenta con funciones de gestión de errores más avanzadas. Puede configurar su máquina de estados para atrapar errores, reintentar los estados fallidos e implementar correctamente los protocolos de manejo de errores.
Los capturadores de Step Functions están disponibles para los estados de tareas, paralelos y mapas, pero no para los errores de ejecución de máquinas de estado de alto nivel. Para gestionar las ejecuciones que anticipas que podrían fallar, la persona que llama puede gestionar el error o puedes agrupar esas ejecuciones en flujos de trabajo secundarios para detectar errores dentro de tu flujo de trabajo principal. También puedes optar por escuchar los TIMED_OUT
eventos de los flujos de trabajo estándar con un EventBridge bus e invocar una acción para gestionar la ejecución fallida.
Ejemplos prácticos de gestión de errores
Para implementar un ejemplo de un flujo de trabajo que incluya la gestión de errores, consulte el Manejo de condiciones de error en una máquina de estados de Step Functions tutorial de esta guía y la gestión de errores
Nombres de error
Step Functions identifica los errores mediante cadenas que distinguen mayúsculas de minúsculas, conocidas 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. Sin embargo, los nombres de los errores no pueden empezar por el States.
prefijo.
Asegúrese de que su código de producción pueda gestionar las excepciones AWS Lambda de servicio (Lambda.ServiceException
yLambda.SdkClientException
). Para obtener más información, consulta cómo hacerlo Gestionar excepciones transitorias del servicio de Lambda en Mejores prácticas.
-
States.ALL
-
Comodín que coincide con cualquier nombre de error conocido.
El tipo de
States.ALL
error debe aparecer solo en unCatcher
y no puede atrapar el error o los tipos deRuntime
error delStates.DataLimitExceeded
terminal.Para obtener más información, consulte States.DataLimitExceeded y States.Runtime.
-
States.DataLimitExceeded
-
Un error terminal que el tipo de
States.ALL
error no puede detectar.Notificación por una de las siguientes condiciones:
-
La salida de un conector supera la cuota de tamaño de la carga útil.
-
La salida de un estado es mayor que la cuota de tamaño de la carga útil.
-
Tras el
Parameters
procesamiento, 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 Service Quotas de Step Functions.
-
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 Establecimiento de umbrales de error para los estados de los mapas distribuidos en Step Functions.-
States.HeartbeatTimeout
-
Estado
Task
que no puede enviar un latido durante un período mayor que el valor deHeartbeatSeconds
.HeartbeatTimeout
está disponible dentro de losRetry
camposCatch
y. -
States.Http.Socket
-
Se produce cuando se agota el tiempo de espera de una tarea HTTP después de 60 segundos. Consulte Cuotas relacionadas con la tarea HTTP.
States.ItemReaderFailed
Se produjo un error en un estado
Map
porque no se pudo leer la fuente del elemento especificada en el campoItemReader
. Para obtener más información, consulteItemReader (Mapa)
.-
States.Permissions
-
Un estado
Task
registró un error porque no tenía privilegios suficientes para ejecutar el código especificado. States.ResultWriterFailed
Un estado
Map
no pudo escribir los resultados en el destino especificado en el campoResultWriter
. Para obtener más información, consulteResultWriter (Mapa)
.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
oOutputPath
a una carga JSON nula. Un errorStates.Runtime
no se puede volver a intentar y siempre provocará que se produzca un error en la ejecución. Un reintento o captura deStates.ALL
no capturará los errores deStates.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 exceptoStates.Timeout
. -
States.Timeout
-
Se informa cuando un
Task
estado dura más tiempo que elTimeoutSeconds
valor o no puede enviar un latido durante un período superior a eseHeartbeatSeconds
valor.Si una máquina de estados anidada arroja un
States.Timeout
, el padre recibirá unStates.TaskedFailed
error.También se informa de un
States.Timeout
error cuando la ejecución completa de una máquina de estados dura más tiempo que elTimeoutSeconds
valor especificado.
nota
Históricamente, los errores no controlados en los tiempos de ejecución de Lambda solo se informaban como. Lambda.Unknown
En los tiempos de ejecución más recientes, los tiempos de espera se indican como Sandbox.Timedout
en el resultado del error.
Cuando Lambda supere el número máximo de invocaciones, se notificará el error. Lambda.TooManyRequestsException
Haga coincidir las Lambda.Unknown
opciones Sandbox.Timedout
con y States.TaskFailed
para gestionar posibles errores. También puede usarloStates.ALL
, pero debe estar solo y al final de la lista.
Para obtener más información sobre los errores de Lambda Handled
y Unhandled
, consulte FunctionError
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 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, consulta 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:
-
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 deIntervalSeconds
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 de0
especifica que el error nunca se volverá a intentar. El valor máximo deMaxAttempts
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, elBackoffRate
valor aumenta en2.0
.Por ejemplo, supongamos que
IntervalSeconds
es 3,MaxAttempts
es 3 yBackoffRate
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 paraMaxDelaySeconds
.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
oNONE
como valores. El valor predeterminado esNONE
.Por ejemplo, supongamos que ha establecido
MaxAttempts
como 3,IntervalSeconds
como 2 yBackoffRate
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 estableceJitterStrategy
comoFULL
, 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.
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
Ejemplos de campo de reintento
Esta sección incluye los siguientes ejemplos de código para Retry
.
Ejemplo 1: Vuelva a intentarlo 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: Vuelva a intentarlo 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:
-
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 estadoZ
a través del campoCatch
.
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
(JSONPath, 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"
} ]
¿Cuántos errores puede atrapar un catcher?
Cada receptor puede especificar varios errores para gestionarlos.
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 JSONPath ejemplo anterior, el primer receptor contiene un ResultPath
campo. Funciona de manera parecida a un campo ResultPath
del nivel superior del estado, lo que genera dos posibilidades:
-
Tome los resultados de la ejecución de ese estado y sobrescriba toda o una parte de la entrada del estado.
-
Toma los resultados y agrégalos a la 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
.
En el caso de los JSONPath flujos de trabajo, si no se especifica el ResultPath
campo, el valor predeterminado es$
, lo 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 AWS CodeBuild o, puede que desee convertir Cause
la cadena 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áquinas de estado mediante 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);
};
Ajustes de tiempo de espera de la función
Cuando cree la función Lambda para los ejemplos, recuerde establecer el Timeout
valor en la configuración avanzada en 11 segundos.
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
}
}
}
Mejores prácticas para gestionar las excepciones de Lambda
Las tareas que hacen referencia a una función de Lambda deben gestionar las excepciones del servicio de Lambda. Para obtener más información, consulte las Gestionar excepciones transitorias del servicio de Lambda prácticas recomendadas.
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
}
}
}
Preservar la entrada de estado y el error en JSONPath
En JSONPath, puede conservar la entrada de estado y el error utilizandoResultPath
. Consulte Se utiliza ResultPath para incluir tanto el error como la entrada en un Catch.