Configurar roteamento, limites e novas tentativas de fila

O Cloud Tasks permite gerenciar a execução de tarefas definindo o roteamento no nível da fila, os limites de taxa de despacho e o comportamento de repetição. É possível configurar essas definições ao criar ou atualizar uma fila. As flags de configuração usadas por gcloud tasks queues create ou gcloud tasks queues update são idênticas.

A configuração de autenticação no nível da fila substitui a autenticação no nível da tarefa. Para mais informações, consulte Usar tarefas de destino HTTP com tokens de autenticação.

Configurar o roteamento no nível da fila

A configuração de roteamento no nível da fila substitui o roteamento definido no nível da tarefa. Isso é útil se você quiser usar o Cloud Tasks como um buffer na frente do serviço de destino ou se precisar mudar o roteamento de todas as tarefas em uma fila.

O roteamento no nível da fila se aplica a:

  • Tarefas que estão na fila
  • Tarefas que são adicionadas à fila depois que o roteamento no nível da fila é definido

Limitações

O roteamento no nível da fila não é compatível com as chaves de criptografia gerenciadas pelo cliente (CMEK) do Cloud Key Management Service (Cloud KMS). Se a CMEK estiver ativada, não será possível:

  • Criar tarefas em uma fila que tenha roteamento no nível da fila
  • Aplicar o roteamento no nível da fila

Configurar o roteamento no nível da fila para tarefas HTTP

É possível configurar uma fila para substituir o roteamento no nível da tarefa ao criar ou atualizar a fila. Para configurar o roteamento no nível da fila, defina o parâmetro uriOverride da fila para a rota preferida.

Se você estiver aplicando o roteamento no nível da fila como uma atualização a uma fila atual, pause a fila antes de aplicar as mudanças e aguarde um minuto após a aplicação das mudanças para retomar a fila.

  1. Para pausar a fila execute o seguinte comando:

      gcloud tasks queues pause QUEUE_ID

    Substitua QUEUE_ID pelo ID da fila.

  2. Atualize ou remova o roteamento no nível da fila.

    • Para atualizar o roteamento no nível da fila, defina o uriOverride parâmetro para a rota atualizada.

    • Para remover o roteamento no nível da fila usando a API REST ou RPC:

      • API REST:envie uma solicitação patch para a fila com um payload vazio e o parâmetro updateMask definido como httpTarget.

      • API RPC:envie uma updateQueueRequest para a fila com um payload vazio e o parâmetro update_mask definido como http_target.

    O exemplo a seguir usa a API REST para atualizar o host para o qual as tarefas são roteadas:

    curl -X PATCH -d @- -i \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  "https://cloudtasks.googleapis.com/v2/projects/PROJECT_ID/locations/LOCATION/queues/QUEUE_ID?updateMask=httpTarget.uriOverride" << EOF
{
  "httpTarget": {"uriOverride":{"host":"NEW_HOST"}}
}
EOF

    Substitua:

    • ACCESS_TOKEN: seu token de acesso. Para receber esse token, execute o seguinte comando no terminal:

      gcloud auth application-default login
gcloud auth application-default print-access-token

    • PROJECT_ID: o ID do seu Google Cloud projeto. Para receber esse ID, execute o seguinte comando no terminal: 

      gcloud config get-value project

    • LOCATION: o local da fila.

    • NEW_HOST: o novo host para o qual você quer que a fila seja roteada.

  3. Aguarde um minuto.

    Pode levar até um minuto para que a nova configuração entre em vigor. Aguardar para retomar a fila ajuda a evitar que as tarefas sejam despachadas com a configuração antiga.

  4. Para retomar a fila, execute o seguinte comando:

    gcloud tasks queues resume QUEUE_ID

Configurar o roteamento no nível da fila para tarefas do App Engine

Para configurar o roteamento no nível da fila para tarefas do App Engine, defina o parâmetro appEngineRoutingOverride da fila para o serviço e a versão do App Engine preferidos.

  1. Configure o roteamento no nível da fila e substitua qualquer roteamento no nível da tarefa:

    gcloud tasks queues update QUEUE_ID \
    --routing-override=service:SERVICE,version:VERSION

    Substitua:

    • QUEUE_ID: o ID da fila (nome abreviado).
    • SERVICE: o serviço de worker do App Engine responsável pelo gerenciamento de tarefas.
    • VERSION: a versão do app.

    Por exemplo, se você configurar um serviço de worker para gerenciar todas as tarefas em uma fila, poderá rotear para esse serviço e a versão padrão:

    gcloud tasks queues update QUEUE_ID \
    --routing-override=service:SERVICE

  2. Para verificar se a fila foi configurada corretamente, execute o seguinte comando:

    gcloud tasks queues describe QUEUE_ID --location=LOCATION

    Substitua LOCATION pelo local da fila.

    A saída será semelhante a esta:

    appEngineRoutingOverride:
  host: SERVICE.PROJECT_ID.appspot.com
  service: SERVICE
name: projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID
rateLimits:
  maxBurstSize: 100
  maxConcurrentDispatches: 1000
  maxDispatchesPerSecond: 500.0
retryConfig:
  maxAttempts: 100
  maxBackoff: 3600s
  maxDoublings: 16
  minBackoff: 0.100s
state: RUNNING

  3. Para remover o roteamento no nível da fila, execute o seguinte comando:

    gcloud tasks queues update QUEUE_ID \
    --clear-routing-override

    Quando o roteamento no nível da fila é removido, o roteamento no nível da tarefa é aplicado às tarefas na fila e às tarefas adicionadas à fila no futuro.

Definir limites de taxa

O limite de taxa determina a taxa máxima em que as tarefas podem ser despachadas por uma fila, independentemente de o despacho ser uma primeira tentativa de tarefa ou uma nova tentativa.

  1. Para definir a taxa máxima e o número de tarefas simultâneas que podem ser despachadas por uma fila, execute o seguinte comando:

    gcloud tasks queues update QUEUE_ID \
    --max-dispatches-per-second=DISPATCH_RATE \
    --max-concurrent-dispatches=MAX_CONCURRENT_DISPATCHES

    Substitua:

    • QUEUE_ID: o ID da fila (nome abreviado).
    • DISPATCH_RATE: a taxa de despacho. Essa é a taxa em que tokens no bucket são atualizados. Em condições em que há um fluxo de tarefas relativamente constante, isso equivale à taxa em que as tarefas são despachadas.
    • MAX_CONCURRENT_DISPATCHES: o número máximo de tarefas na fila que podem ser executadas de uma só vez.

    Por exemplo, se você criou uma fila sem definir nenhum parâmetro, poderá atualizar o número máximo de tarefas simultâneas executando o seguinte comando:

    gcloud tasks queues update QUEUE_ID \
    --max-concurrent-dispatches=MAX_CONCURRENT_DISPATCHES

  2. Para verificar se a fila foi configurada corretamente, execute o seguinte comando:

    gcloud tasks queues describe QUEUE_ID --location=LOCATION

    Substitua LOCATION pelo local da fila.

    A saída será semelhante a esta:

    name: projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID
rateLimits:
  maxBurstSize: 100
  maxConcurrentDispatches: MAX_CONCURRENT_DISPATCHES
  maxDispatchesPerSecond: 500.0
retryConfig:
  maxAttempts: 100
  maxBackoff: 3600s
  maxDoublings: 16
  minBackoff: 0.100s
state: RUNNING

Métodos para definir taxas de processamento de fila

É possível definir taxas de processamento de fila usando a API Cloud Tasks ou fazendo upload de um arquivo queue.yaml. Os dois métodos resultam em filas que usam o mesmo mecanismo subjacente.

Em ambos os casos, a fila usa o token bucket algoritmo para controlar a taxa de execução da tarefa. Cada fila nomeada tem um bucket que contém os tokens.

Cada vez que o aplicativo executa uma tarefa, um token é removido do bucket. A fila continua processando tarefas até que o bucket fique sem tokens. O sistema recarrega o bucket com novos tokens continuamente com base na taxa max_dispatches_per_second especificada para a fila. Se a fila contiver tarefas a serem processadas e o bucket da fila contiver tokens, o sistema processará simultaneamente quantas tarefas houver tokens, até o valor max_concurrent_dispatches definido.

Uma carga desigual pode permitir o aumento significativo do número de tokens no bucket, o que pode levar a bursts de processamento quando uma sequência de solicitações é recebida. Nesse caso, sua fila pode apresentar uma taxa de despacho real que excede a taxa max_dispatches_per_second, consumindo recursos do sistema e competindo com solicitações de veiculação do usuário. Nos casos em que você usa filas para gerenciar taxas de despacho com base em SLAs relativamente lentos para serviços de downstream, isso pode gerar erros, como HTTP 429 (excesso de solicitações) ou HTTP 503 (serviço indisponível).

  • Ao usar qualquer método de API Cloud Tasks, você tem dois campos para definir a taxa de despacho da fila:

    • max_dispatches_per_second
    • max_concurrent_dispatches

    Um terceiro campo, max_burst_size, é calculado pelo sistema com base no valor definido para max_dispatches_per_second. Para mais informações, consulte RateLimits mensagens.

  • Ao usar o queue.yaml método, é possível definir todos os três elementos:

    • max_concurrent_requests, que é equivalente a max_concurrent_dispatches
    • rate, que é equivalente a max_dispatches_per_second
    • bucket_size, que é equivalente a max_burst_size

Na maioria dos casos, usar o método de API Cloud Tasks e permitir que o sistema defina max_burst_size produz uma taxa muito eficiente para o gerenciamento de bursts de solicitação. Em alguns casos, no entanto, especialmente quando a taxa necessária é relativamente lenta, usar o método queue.yaml para definir manualmente bucket_size com um valor baixo ou definir max_concurrent_dispatches com um valor baixo usando a API Cloud Tasks pode lhe dar mais controle.

Definir parâmetros de tentativa

Se uma tarefa não for concluída com sucesso, o Cloud Tasks fará uma nova tentativa com a tarefa com espera exponencial de acordo com os parâmetros que você configurou. Depois que uma tarefa é executada com sucesso, ela é removida da fila. Em todos os casos, o limite máximo de retenção de tarefas também se aplica.

Opcionalmente, é possível especificar uma configuração de nova tentativa no nível da tarefa que substitui a configuração de nova tentativa no nível da fila. Para mais informações, consulte Definir parâmetros de nova tentativa para uma tarefa.

  1. Para especificar o número máximo de novas tentativas de tarefas com falha na fila, defina um limite de tempo para as tentativas e controle o intervalo entre as tentativas executando o seguinte comando:

    gcloud tasks queues update QUEUE_ID \
    --max-attempts=MAX_ATTEMPTS \
    --max-retry-duration=MAX_RETRY_DURATION \
    --min-backoff=MIN_INTERVAL \
    --max-backoff=MAX_INTERVAL \
    --max-doublings=MAX_DOUBLINGS

    Substitua:

    • QUEUE_ID: o ID da fila (nome abreviado).
    • MAX_ATTEMPTS: o número máximo de tentativas para uma tarefa, incluindo a primeira. Para permitir novas tentativas ilimitadas, defina esse valor como -1. MAX_RETRY_DURATION ainda se aplica mesmo que MAX_ATTEMPTS seja atingido ou definido como -1.
    • MAX_RETRY_DURATION: o tempo máximo para repetir uma tarefa com falha medida a partir da primeira tentativa da tarefa. O valor precisa ser uma string que termine em "s", como 5s. Para especificar uma duração ilimitada, defina esse valor como 0s. MAX_ATTEMPTS ainda se aplica mesmo que MAX_RETRY_DURATION seja atingido ou definido como 0s.
    • MIN_INTERVAL: o tempo mínimo de espera entre as tentativas. O valor precisa ser uma string que termine em "s", como 5s.
    • MAX_INTERVAL: o tempo máximo de espera entre as tentativas. O valor precisa ser uma string que termine em "s", como 5s.

    • MAX_DOUBLINGS: o número máximo de vezes que o intervalo entre novas tentativas de tarefas com falha será duplicado antes que o aumento se torne constante. O intervalo de repetição de uma tarefa começa em MIN_INTERVAL, depois duplica MAX_DOUBLINGS vezes, aumenta linearmente e, finalmente, tenta novamente em intervalos de MAX_INTERVAL até MAX_ATTEMPTS vezes.

      Por exemplo, se MIN_INTERVAL for 10s, MAX_INTERVAL for 300s, e MAX_DOUBLINGS for 3, o intervalo de repetição será duplicado 3 vezes, aumentará linearmente em 2^3 * 10s e, em seguida, tentará novamente em intervalos de MAX_INTERVAL até que a tarefa tenha sido tentada MAX_ATTEMPTS vezes: 10s, 20s, 40s, 80s, 160s, 240s, 300s, 300s e assim por diante.

Para mais detalhes sobre os parâmetros, consulte as RetryConfig configurações do Queue recurso.

  1. Para verificar se a fila foi configurada corretamente, execute o seguinte comando:

    gcloud tasks queues describe QUEUE_ID --location=LOCATION

    Substitua LOCATION pelo local da fila.

    A saída precisa conter os parâmetros de nova tentativa definidos.

A seguir