Reintentos y control de errores de Azure FunctionsAzure Functions error handling and retries

El control de los errores en Azure Functions es importante para evitar la pérdida de datos, eventos perdidos y para supervisar el estado de la aplicación.Handling errors in Azure Functions is important to avoid lost data, missed events, and to monitor the health of your application.

En este artículo se describen las estrategias generales para el control de errores junto con vínculos a errores específicos de enlace.This article describes general strategies for error handling along with links to binding-specific errors.

Control de erroresHandling errors

Los errores que se producen en una instancia de Azure Functions pueden provenir de cualquiera de los orígenes siguientes:Errors raised in an Azure Functions can come from any of the following origins:

  • Uso de desencadenadores y enlaces de Azure Functions integradosUse of built-in Azure Functions triggers and bindings
  • Llamadas a las API de los servicios de Azure subyacentesCalls to APIs of underlying Azure services
  • Llamadas a puntos de conexión RESTCalls to REST endpoints
  • Llamadas a bibliotecas de cliente, paquetes o API de tercerosCalls to client libraries, packages, or third-party APIs

Seguir las prácticas recomendadas de control de errores es importante para evitar la pérdida de datos o mensajes.Following good error handling practices is important to avoid loss of data or missed messages. Entre las prácticas recomendadas de control de errores se incluyen las acciones siguientes:Recommended error handling practices include the following actions:

Uso del control de errores estructuradoUse structured error handling

La captura y el registro de los errores son fundamentales para supervisar el estado de la aplicación.Capturing and logging errors is critical to monitoring the health of your application. El nivel superior de cualquier código de función debe incluir un bloque try/catch.The top-most level of any function code should include a try/catch block. En el bloque catch, puede capturar y registrar errores.In the catch block, you can capture and log errors.

Directivas de reintentos (versión preliminar)Retry policies (preview)

Se puede definir una directiva de reintentos en cualquier función para cualquier tipo de desencadenador en la aplicación de funciones.A retry policy can be defined on any function for any trigger type in your function app. La directiva de reintentos vuelve a ejecutar una función hasta que se ejecuta correctamente o hasta que se produce el número máximo de reintentos.The retry policy re-executes a function until either successful execution or until the maximum number of retries occur. Las directivas de reintentos se pueden definir para todas las funciones de una aplicación o para funciones individuales.Retry policies can be defined for all functions in an app or for individual functions. De forma predeterminada, una aplicación de funciones no volverá a intentar los mensajes (aparte de los desencadenadores específicos que tienen una directiva de reintentos en el origen del desencadenador).By default, a function app won't retry messages (aside from the specific triggers that have a retry policy on the trigger source). Se evalúa una directiva de reintentos cada vez que una ejecución produce una excepción no detectada.A retry policy is evaluated whenever an execution results in an uncaught exception. Como procedimiento recomendado, debería detectar todas las excepciones del código y volver a generar los errores que debieran dar lugar a un reintento.As a best practice, you should catch all exceptions in your code and rethrow any errors that should result in a retry. Los puntos de comprobación de Event Hubs y Azure Cosmos DB no se escribirán hasta que se haya completado la directiva de reintentos para la ejecución, lo que significa que el progreso en esa partición se pausará hasta que se complete el lote actual.Event Hubs and Azure Cosmos DB checkpoints won't be written until the retry policy for the execution has completed, meaning progressing on that partition is paused until the current batch has completed.

Opciones de la directiva de reintentosRetry policy options

Las opciones siguientes están disponibles para definir una directiva de reintentos.The following options are available for defining a retry policy.

El número máximo de reintentos es el número máximo de veces que se reintenta una ejecución antes de que se produzca un error eventual.Max Retry Count is the maximum number of times an execution is retried before eventual failure. Un valor de -1 significa que se reintentará indefinidamente.A value of -1 means to retry indefinitely. El número de reintentos actual se almacena en la memoria de la instancia.The current retry count is stored in memory of the instance. Es posible que una instancia tenga un error entre reintentos.It's possible that an instance has a failure between retry attempts. Cuando se produce un error en una instancia durante una directiva de reintentos, se pierde el número de reintentos.When an instance fails during a retry policy, the retry count is lost. Cuando hay errores de instancia, los desencadenadores como Event Hubs, Azure Cosmos DB y Queue Storage pueden reanudar el procesamiento y reintentar el lote en una nueva instancia, con el número de reintentos restablecido en cero.When there are instance failures, triggers like Event Hubs, Azure Cosmos DB, and Queue storage are able to resume processing and retry the batch on a new instance, with the retry count reset to zero. Otros desencadenadores, como HTTP y el temporizador, no se reanudan en una nueva instancia.Other triggers, like HTTP and timer, don't resume on a new instance. Esto significa que el número máximo de reintentos es un esfuerzo óptimo y, en algunos casos excepcionales, una ejecución puede volver a intentarse más que el máximo de veces, o bien, para los desencadenadores como HTTP y el temporizador reintentarse menos que el número máximo de veces.This means that the max retry count is a best effort, and in some rare cases an execution could be retried more than the maximum, or for triggers like HTTP and timer be retried less than the maximum.

La estrategia de reintento controla cómo se comportan los reintentos.Retry Strategy controls how retries behave. A continuación se indican dos opciones de reintento admitidas:The following are two supported retry options:

OpciónOption DescripciónDescription
fixedDelay Puede transcurrir un período de tiempo especificado entre cada reintento.A specified amount of time is allowed to elapse between each retry,
exponentialBackoff El primer reintento espera el retraso mínimo.The first retry waits for the minimum delay. En los reintentos posteriores, se agrega el tiempo de manera exponencial a la duración inicial de cada reintento, hasta que se alcanza el retraso máximo.On subsequent retries, time is added exponentially to the initial duration for each retry, until the maximum delay is reached. El retroceso exponencial agrega una pequeña aleatorización a los retrasos para escalonar los reintentos en escenarios de alto rendimiento.Exponential back-off adds some small randomization to delays to stagger retries in high-throughput scenarios.

Configuración del nivel de la aplicaciónApp level configuration

Se puede definir una directiva de reintentos para todas las funciones de una aplicación mediante el archivo host.json.A retry policy can be defined for all functions in an app using the host.json file.

Configuración del nivel de la funciónFunction level configuration

Se puede definir una directiva de reintentos para una función específica.A retry policy can be defined for a specific function. La configuración específica de la función tiene prioridad sobre la configuración de nivel de la aplicación.Function-specific configuration takes priority over app-level configuration.

Retraso fijo entre reintentosFixed delay retry

Los reintentos requieren el paquete NuGet Microsoft.Azure.WebJobs >= 3.0.23Retries require NuGet package Microsoft.Azure.WebJobs >= 3.0.23

[FunctionName("EventHubTrigger")]
[FixedDelayRetry(5, "00:00:10")]
public static async Task Run([EventHubTrigger("myHub", Connection = "EventHubConnection")] EventData[] events, ILogger log)
{
// ...
}

Reintento de retroceso exponencialExponential backoff retry

Los reintentos requieren el paquete NuGet Microsoft.Azure.WebJobs >= 3.0.23Retries require NuGet package Microsoft.Azure.WebJobs >= 3.0.23

[FunctionName("EventHubTrigger")]
[ExponentialBackoffRetry(5, "00:00:04", "00:15:00")]
public static async Task Run([EventHubTrigger("myHub", Connection = "EventHubConnection")] EventData[] events, ILogger log)
{
// ...
}
Propiedad de function.jsonfunction.json property Propiedad de atributoAttribute Property DescripciónDescription
strategystrategy n/an/a Necesario.Required. Estrategia de reintentos que se usará.The retry strategy to use. Los valores válidos son fixedDelay y exponentialBackoff.Valid values are fixedDelay or exponentialBackoff.
maxRetryCountmaxRetryCount n/an/a Necesario.Required. Número máximo de reintentos permitidos por ejecución de función.The maximum number of retries allowed per function execution. -1 significa que se reintentará indefinidamente.-1 means to retry indefinitely.
delayIntervaldelayInterval n/an/a Retraso que se utilizará entre reintentos al usar la estrategia fixedDelay.The delay that will be used between retries when using fixedDelay strategy.
minimumIntervalminimumInterval n/an/a Retraso entre reintentos mínimo al usar la estrategia exponentialBackoff.The minimum retry delay when using exponentialBackoff strategy.
maximumIntervalmaximumInterval n/an/a Retraso entre reintentos máximo al usar la estrategia exponentialBackoff.The maximum retry delay when using exponentialBackoff strategy.

Limitaciones de reintentos durante la versión preliminarRetry limitations during preview

  • En los proyectos de .NET, es posible que tenga que incorporar una versión de Microsoft.Azure.WebJobs >= 3.0.23.For .NET projects, you may need to manually pull in a version of Microsoft.Azure.WebJobs >= 3.0.23.
  • En el plan de consumo, la aplicación se puede reducir verticalmente hasta cero mientras se reintentan los mensajes finales de una cola.In the consumption plan, the app may be scaled down to zero while retrying the final messages in a queue.
  • En el plan de consumo, la aplicación se puede reducir verticalmente mientras se realizan los reintentos.In the consumption plan, the app may be scaled down while performing retries. Para obtener unos resultados óptimos, elija un intervalo de reintentos <= 00:01:00 y <= 5 reintentos.For best results, choose a retry interval <= 00:01:00 and <= 5 retries.

Uso de la compatibilidad con los reintentos sobre la resistencia del desencadenadorUsing retry support on top of trigger resilience

La directiva de reintentos de la aplicación de funciones es independiente de los reintentos o la resistencia que proporciona el desencadenador.The function app retry policy is independent of any retries or resiliency that the trigger provides. La directiva de reintentos de función solo se coloca sobre un reintento resistente del desencadenador.The function retry policy will only layer on top of a trigger resilient retry. Por ejemplo, si usa Azure Service Bus, de manera predeterminada, las colas tienen un número de entregas de mensajes de 10.For example, if using Azure Service Bus, by default queues have a message delivery count of 10. El número de entregas predeterminado significa que después de 10 intentos de entrega de un mensaje en cola, Service Bus coloca el mensaje en la cola de mensajes fallidos.The default delivery count means after 10 attempted deliveries of a queue message, Service Bus will dead-letter the message. Puede definir una directiva de reintentos para una función que tenga un desencadenador de Service Bus, pero los reintentos se van a colocar sobre los intentos de entrega de Service Bus.You can define a retry policy for a function that has a Service Bus trigger, but the retries will layer on top of the Service Bus delivery attempts.

Por ejemplo, si ha usado el número de entregas predeterminado de Service Bus de 10 y ha definido una directiva de reintentos de función de 5.For instance, if you used the default Service Bus delivery count of 10, and defined a function retry policy of 5. Primero, el mensaje se quita de la cola, lo que incrementa la cuenta de entrega de Service Bus en 1.The message would first dequeue, incrementing the service bus delivery account to 1. Si se ha producido un error en cada ejecución después de cinco intentos de desencadenar el mismo mensaje, ese mensaje se marca como abandonado.If every execution failed, after five attempts to trigger the same message, that message would be marked as abandoned. Service Bus vuelve a poner en cola el mensaje inmediatamente, desencadena la función e incrementa el número de entregas en 2.Service Bus would immediately requeue the message, it would trigger the function and increment the delivery count to 2. Por último, después de 50 intentos posibles (10 entregas de Service Bus * 5 reintentos de función por entrega), el mensaje se abandona y se desencadena la colocación en la cola de mensajes fallidos en Service Bus.Finally, after 50 eventual attempts (10 service bus deliveries * five function retries per delivery), the message would be abandoned and trigger a dead-letter on service bus.

Advertencia

No se recomienda establecer el número de entregas de un desencadenador como las colas de Service Bus en 1, lo que significa que el mensaje se colocaría inmediatamente en la cola de mensajes fallidos después de un único ciclo de reintentos de función.It is not recommended to set the delivery count for a trigger like Service Bus Queues to 1, meaning the message would be dead-lettered immediately after a single function retry cycle. Esto se debe a que los desencadenadores proporcionan resistencia con los reintentos, mientras que la directiva de reintentos de función es el mejor esfuerzo y puede dar lugar a un número total de reintentos menor que el deseado.This is because triggers provide resiliency with retries, while the function retry policy is best effort and may result in less than the desired total number of retries.

Desencadenadores con resistencia adicional o reintentosTriggers with additional resiliency or retries

Los siguientes desencadenadores admiten reintentos en el origen del desencadenador:The following triggers support retries at the trigger source:

De manera predeterminada, la mayoría de los desencadenadores reintenta las solicitudes hasta cinco veces.By default, most triggers retry requests up to five times. Después del quinto reintento, Azure Queue Storage escribe un mensaje en una cola de mensajes dudosos.After the fifth retry, both the Azure Queue storage will write a message to a poison queue. La directiva predeterminada de colas y temas de Service Bus escribe un mensaje en una cola de mensajes fallidos después de 10 intentos.The default Service Bus queue and topic policy will write a message to a dead-letter queue after 10 attempts.

Códigos de error de enlaceBinding error codes

Cuando se realizan integraciones con los servicios de Azure, pueden originarse errores desde las API de los servicios subyacentes.When integrating with Azure services, errors may originate from the APIs of the underlying services. La información relacionada con los errores específicos de enlace está disponible en la sección Excepciones y códigos de retorno de los siguientes artículos:Information relating to binding-specific errors is available in the Exceptions and return codes section of the following articles: