Novas tentativas da AWS CLI

Este tópico descreve como a AWS CLI pode observar chamadas para AWS falharem devido a problemas inesperados. Esses problemas podem ocorrer no lado do servidor ou podem falhar devido à limitação de taxa do serviço da AWS que você está tentando chamar. Esses tipos de falhas geralmente não exigem tratamento especial e a chamada é feita automaticamente novamente, em geral após um breve período de espera. A AWS CLI oferece muitos recursos para ajudar a repetir chamadas de cliente para os serviços da AWS quando esses tipos de erros ou exceções ocorrem.

Modos de novas tentativas disponíveis

A AWS CLI oferece vários modos para escolha dependendo da sua versão:

• Modo de novas tentativas herdado
• Modo de nova tentativa padrão
• Modo de nova tentativa adaptável

Modo de novas tentativas herdado

O modo herdado usa um manipulador de novas tentativas mais antigo e com funcionalidade limitada que inclui:

• Um valor padrão de 4 para o máximo de novas tentativas, totalizando 5 tentativas de chamada. Esse valor pode ser sobrescrito por meio do parâmetro de configuração max_attempts.

• No DynamoDB, o valor padrão máximo de novas tentativas é nove, totalizando dez tentativas de chamada. Esse valor pode ser sobrescrito por meio do parâmetro de configuração max_attempts.

• Novas tentativas para o seguinte número limitado de erros e exceções:

  • Erros gerais de soquete e conexão:

    • ConnectionError

    • ConnectionClosedError

    • ReadTimeoutError

    • EndpointConnectionError

  • Erros e exceções de controle de utilização ou limitação no lado do serviço:

    • Throttling

    • ThrottlingException

    • ThrottledException

    • RequestThrottledException

    • ProvisionedThroughputExceededException

• Novas tentativas em vários códigos de status HTTP, incluindo 429, 500, 502, 503, 504 e 509.

• Qualquer tentativa de repetição incluirá um recuo exponencial por um fator de base 2.

Modo de nova tentativa padrão

O modo padrão é um conjunto padrão de regras de novas tentativas nos AWS SDKs com mais funcionalidade do que herdado. Esse é o modo padrão para a AWS CLI versão 2. O modo padrão foi criado para a AWS CLI versão 2 e é compatível com a AWS CLI versão 1. A funcionalidade do modo padrão inclui:

• Um valor padrão de 2 para o máximo de novas tentativas, totalizando 3 tentativas de chamada. Esse valor pode ser sobrescrito por meio do parâmetro de configuração max_attempts.

• Novas tentativas para a seguinte lista estendida de erros/exceções:

  • Erros e exceções transientes

    • RequestTimeout

    • RequestTimeoutException

    • PriorRequestNotComplete

    • ConnectionError

    • HTTPClientError

  • Erros e exceções de controle de utilização ou limitação no lado do serviço:

    • Throttling

    • ThrottlingException

    • ThrottledException

    • RequestThrottledException

    • TooManyRequestsException

    • ProvisionedThroughputExceededException

    • TransactionInProgressException

    • RequestLimitExceeded

    • BandwidthLimitExceeded

    • LimitExceededException

    • RequestThrottled

    • SlowDown

    • EC2ThrottledException

• Novas tentativas em códigos de erro não descritivos transientes. Especificamente, estes códigos de status HTTP: 500, 502, 503, 504.

• Qualquer nova tentativa incluirá um recuo exponencial por um fator de base 2 para um tempo máximo de recuo de 20 segundos.

Modo de nova tentativa adaptável

Atenção

O modo adaptativo é um experimental e está sujeito a modificações, tanto em suas características quanto em seu comportamento.

O modo de nova tentativa adaptativo é um modo de repetição experimental que inclui todos os recursos do modo padrão. Além dos recursos do modo padrão, o modo adaptativo também introduz limitação de taxa no lado do cliente através do uso de um bucket de token e variáveis de limite de taxa que são atualizadas dinamicamente com cada tentativa de repetição. Esse modo oferece flexibilidade de novas tentativas no lado do cliente que se adapta à resposta de estado de erro e exceção de um serviço da AWS.

Com cada nova tentativa, o modo adaptativo modifica as variáveis de limite de taxa com base no erro, exceção ou código de status HTTP apresentado na resposta do serviço da AWS. Essas variáveis de limite de taxa são usadas para calcular uma nova taxa de chamada para o cliente. Cada resposta HTTP de exceção/erro ou não bem-sucedida (fornecida na lista acima) de um serviço da AWS atualiza as variáveis de limite de taxa à medida que as tentativas ocorrerem até alcançarem êxito, o bucket de token se esgotar ou o valor máximo de tentativas configurado ser atingido.

Configuração um modo de nova tentativa

A AWS CLI inclui uma variedade de configurações de novas tentativas, bem como métodos de configuração a serem considerados ao criar seu objeto cliente.

Métodos de configuração disponíveis

Na AWS CLI, os usuários podem configurar novas tentativas das seguintes formas:

• Variáveis de ambiente

• Arquivo de configuração da AWS CLI

Os usuários podem personalizar as seguintes opções de novas tentativas:

• Modo de repetição: especifica qual modo de repetição será usado pela AWS CLI. Conforme descrito anteriormente existem três modos de repetição disponíveis: herdado (o modo usado por padrão), padrão e adaptativo. O valor padrão para a AWS CLI e para a versão 2 é padrão.

• Máximo de tentativas: especifica um valor para o máximo de novas tentativas utilizadas pelo manipulador de novas tentativas da AWS CLI, onde a chamada inicial conta para o valor fornecido por você. O valor padrão é 5.

Definição de uma configuração de novas tentativas em suas variáveis de ambiente

Para definir a configuração de novas tentativas para oAWS CLI, atualize as variáveis de ambiente do seu sistema operacional.

As variáveis de ambiente de novas tentativas são:

• AWS_RETRY_MODE

• AWS_MAX_ATTEMPTS

Para obter mais informações sobre variáveis de ambiente, consulte Variáveis de ambiente para configurar o AWS CLI.

Definição de uma configuração de nova tentativa em seu arquivo de configuração da AWS

Para alterar a configuração de novas tentativas, atualize o arquivo de configuração global da AWS. O local padrão do seu arquivo de configuração da AWS é ~/.aws/config.

Exemplo de um arquivo de configuração da AWS:

[default]
retry_mode = standard
max_attempts = 6

Para obter mais informações sobre arquivos de configuração, consulte Configurações do arquivo de configuração e credenciais.

Visualização de logs de novas tentativas

A AWS CLI usa a metodologia de novas tentativas e log do Boto3. Você pode usar a opção --debug em qualquer comando para receber logs de depuração. Para obter informações sobre como usar a opção --debug, consulte Opções de linha de comando.

Se você procurar “retry” em seus logs de depuração, encontrará as informações de repetição de que necessita. As entradas de log do cliente para tentativas de repetição dependem do modo de repetição ativado.

Modo herdado:

As mensagens de novas tentativas são geradas por botocore.retryhandler. Você verá uma de três mensagens:

• No retry needed

• Retry needed, action of: <action_name>

• Reached the maximum number of retry attempts: <attempt_number>

Modo padrão ou adaptativo:

As mensagens de novas tentativas são geradas por botocore.retries.standard. Você verá uma de três mensagens:

• No retrying request

• Retry needed, retrying request after delay of: <delay_value>

• Retry needed but retry quota reached, not retrying request

Para obter o arquivo de definição completa de novas tentativas do botocore, consulte _retry.jsonno Repositório do botocore no GitHub.