Como Otimizar Retries e Visibility Timeout no Celery em Alta Escala: Evite Execuções Duplicadas e Perda de Tarefas em Produção

Em sistemas distribuídos em Python, filas de tarefas em segundo plano costumam crescer rapidamente com o aumento de tráfego. Nessa fase, começam a aparecer sintomas difíceis de diagnosticar, como tarefas duplicadas, mensagens “sumindo” e picos inesperados de novas tentativas. Esses problemas raramente são “bugs simples” e, com frequência, têm origem em configurações de confirmação de mensagem e em políticas de nova tentativa.

No ecossistema do Celery, dois conceitos determinam grande parte do comportamento em alta escala: **retries** (novas tentativas) e **visibility timeout** (tempo de invisibilidade no broker). Quando esses parâmetros são mal calibrados, o sistema pode executar a mesma tarefa duas vezes sem erro aparente, gerar tempestades de tentativas e até produzir perdas de estado em fluxos longos. O entendimento correto desses mecanismos permite obter execução previsível, reduzir trabalho redundante e proteger a integridade dos dados.

Celery em alta escala e o problema das novas tentativas

O Celery é uma fila de tarefas distribuída, na qual processos chamados **workers** consomem mensagens de um **broker** (intermediador), como Redis, RabbitMQ ou SQS. Em volume baixo, falhas pontuais e novas tentativas raramente causam danos importantes, pois há folga de capacidade e menor chance de colisões. Em alto throughput, a mesma política de tentativas pode criar efeito dominó, com filas crescendo mais rápido do que a capacidade de consumo. Isso resulta em saturação de workers, aumento de latência e instabilidade operacional.

Em cenários críticos, aparecem padrões como tempestades de retry, em que uma falha comum (por exemplo, API instável) gera milhares de tentativas simultâneas. Outro padrão é a execução duplicada, em que dois workers acabam processando o mesmo trabalho em momentos diferentes. Também pode ocorrer perda de rastreabilidade, quando a tarefa parece ter sido executada, mas o estado final não é persistido como esperado. Esses efeitos não dependem apenas do código da tarefa, mas também de como o broker controla visibilidade e confirmações.

O que é visibility timeout e por que causa duplicidade silenciosa

O **visibility timeout** é o período em que o broker mantém uma mensagem “invisível” para outros workers após ela ser entregue para processamento. Se o worker não confirmar (dar **ack**, de acknowledgment) dentro desse período, o broker assume que o worker falhou e recoloca a mensagem na fila. Isso é uma proteção importante contra quedas de processo, travamentos e perda de conexão. O problema surge quando o tempo configurado é menor do que o tempo real de execução da tarefa.

Em uma tarefa longa, a confirmação pode ocorrer apenas no final, e a mensagem fica “pendurada” durante toda a execução. Se o visibility timeout expirar no meio do processamento, a mesma mensagem pode reaparecer e ser consumida por outro worker. Nesse caso, dois processamentos avançam em paralelo ou em sequência, sem necessariamente gerar exceções. O resultado é uma duplicidade silenciosa, com riscos de inconsistência de dados, cobranças duplicadas, reprocessamento pesado e resultados divergentes.

Exemplo prático de duplicidade por timeout insuficiente

Um exemplo comum é o processamento de vídeo, em que a tarefa pode levar vários minutos por depender de CPU, I/O e ferramentas externas. Se a tarefa demora 5 minutos e o visibility timeout está em 3 minutos, o broker pode reenviar a mesma mensagem no terceiro minuto. O primeiro worker pode continuar rodando, mas um segundo worker começa a executar o mesmo trabalho. Como não existe “alarme automático” nesse ponto, a duplicidade pode passar despercebida em logs comuns.

Exemplo de situação: uma tarefa de transcodificação inicia às 12:00 e termina às 12:05, mas o visibility timeout é 180s. Às 12:03, a mensagem volta para a fila e outro worker inicia nova transcodificação do mesmo arquivo.

Esse tipo de efeito é mais frequente quando há variação de tempo de execução, como lentidão de rede, filas internas, dependência de serviços externos e picos de uso. A calibração não pode considerar apenas a “média”; precisa considerar o pior caso razoável. Caso contrário, o sistema pode ser estável em testes e falhar em horários de pico.

Diferença entre retries do Celery e retries do broker

No Celery existem novas tentativas explícitas e controladas pelo código, enquanto o broker pode fazer reentrega implícita por falta de confirmação. As **retries do Celery** ocorrem quando a tarefa chama mecanismos como **self.retry** ou quando se usa **autoretry_for**, e costumam produzir logs claros e contagem de tentativas. Já as “tentativas” do broker acontecem quando o ack não chega a tempo e a mensagem é recolocada na fila. Esse segundo comportamento pode parecer “fantasma”, porque a aplicação não pediu retry.

O risco é assumir que somente as retries do Celery importam, e ignorar reentregas por timeout. Quando ambos atuam juntos, as filas podem multiplicar tráfego rapidamente: uma exceção gera retry do Celery e, ao mesmo tempo, um timeout de visibilidade pode gerar reentrega. Em alta escala, essa combinação pode dobrar ou triplicar o volume processado sem aumento real de trabalho útil. A separação conceitual entre “retry do app” e “reentrega do broker” é essencial para diagnosticar duplicidade.

Configuração do visibility timeout para tarefas longas

A prática mais segura é manter o **visibility_timeout** maior do que o maior tempo de execução esperado da tarefa, incluindo variações. Além do tempo do código, entram na conta atrasos de rede, sobrecarga do worker, lentidão de serviços externos e qualquer backoff interno. Também é importante lembrar que tarefas encadeadas e fluxos com I/O podem ter caudas longas de execução. Em ambientes com picos, o tempo máximo pode ser bem maior do que o observado em horários tranquilos.

O broker e o transporte do Celery controlam esse valor por configurações, normalmente em **broker_transport_options**. A configuração exata e o comportamento variam entre Redis, SQS e RabbitMQ, e isso impacta como o timeout é aplicado. Mesmo assim, a ideia central é a mesma: garantir que a mensagem não volte para a fila enquanto ainda há uma execução legítima em andamento. A seguir está um exemplo de configuração típica usada quando há tarefas longas.

from celery import Celery

app = Celery(
    "minha_app",
    broker="redis://localhost:6379/0",
    backend="redis://localhost:6379/1",
)

# Opções de transporte: o nome e o efeito podem variar por broker.
# Em brokers que suportam, visibility_timeout controla reentrega se não houver ack no prazo.
app.conf.broker_transport_options = {
    "visibility_timeout": 600  # 10 minutos
}

Confirmação tardia com acks_late e seus efeitos

O parâmetro **acks_late** controla quando a tarefa envia o ack ao broker. Com **acks_late=False** (comportamento comum), o ack pode ser enviado antes do processamento terminar, reduzindo risco de duplicidade, mas aumentando risco de perda de trabalho se o worker cair no meio. Com **acks_late=True**, o ack acontece após a conclusão bem-sucedida, o que melhora a confiabilidade contra quedas. Porém, essa escolha exige um visibility timeout compatível com a duração do processamento.

Em tarefas longas, **acks_late=True** costuma ser desejável, pois evita “sumir” com mensagens em caso de crash. Mesmo assim, se o visibility timeout for baixo, a tarefa pode ser reentregue antes do final e rodar duas vezes. Para operações críticas, também é relevante a configuração **task_acks_on_failure_or_timeout**, que influencia se haverá ack em falhas ou timeouts. O equilíbrio entre confiabilidade e duplicidade depende do tipo de trabalho e de como a idempotência é tratada.

from celery import Celery

app = Celery("processamento", broker="redis://localhost:6379/0")
app.conf.update(
    task_acks_late=True,                 # confirma só depois do sucesso
    task_reject_on_worker_lost=True,     # se o worker morrer, rejeita para reentregar
)

@app.task(bind=True, acks_late=True)
def processar_video(self, video_id: str) -> str:
    # Processamento pesado simulado
    # Em caso de queda do worker, a mensagem tende a ser reentregue
    return f"Vídeo {video_id} processado com sucesso"

Estratégias de retry: backoff, jitter e limite de tentativas

Uma política de **retry_backoff** aplica espera progressiva entre tentativas, reduzindo pressão sobre serviços que estão instáveis. O **jitter** adiciona variação aleatória ao tempo de espera, evitando que milhares de tarefas tentem novamente ao mesmo tempo. Já o **max_retries** define um teto para impedir loops infinitos. Em alta escala, esses três elementos são fundamentais para evitar tempestades de retries e proteger bancos de dados e APIs.

No Celery, retries podem ser configuradas por **autoretry_for** ou por chamadas explícitas a retry. Em falhas previsíveis, como respostas HTTP 500 ou timeouts de rede, retries com backoff são úteis. Em falhas lógicas, como validações inválidas, retries só desperdiçam recursos. A separação entre falhas transitórias e definitivas reduz custos e melhora o tempo de recuperação.

import requests
from celery import Celery

app = Celery("integracoes", broker="redis://localhost:6379/0")

@app.task(
    bind=True,
    autoretry_for=(requests.RequestException,),
    retry_backoff=30,                 # backoff exponencial a partir de 30s
    retry_jitter=True,                # adiciona aleatoriedade
    retry_kwargs={"max_retries": 5},  # limita tentativas
)
def buscar_em_api(self, url: str) -> int:
    resposta = requests.get(url, timeout=10)
    resposta.raise_for_status()
    return resposta.status_code

Idempotência: o requisito essencial para evitar danos em duplicidade

**Idempotência** significa que executar a mesma operação mais de uma vez produz o mesmo efeito final, como se tivesse sido executada apenas uma vez. Em sistemas de filas, idempotência não é opcional, porque reentregas podem acontecer por falha, timeout, reinício de worker ou reprocessamentos. Mesmo com configurações perfeitas, ainda existe a possibilidade de duplicidade por eventos raros. A proteção real vem do desenho do efeito da tarefa sobre dados e sistemas externos.

Uma forma simples de idempotência é registrar em banco que um identificador já foi processado e recusar repetições. Outra abordagem é usar uma **chave de deduplicação**, como um hash do conteúdo ou um id de transação. Também é comum usar bloqueios (locks) no Redis para garantir execução única por chave, embora isso exija cuidado com expiração e falhas. Em pagamentos, faturamento e emissão de documentos, idempotência evita prejuízos e inconsistências.

O exemplo a seguir mostra uma estrutura básica de deduplicação usando uma chave de transação, com persistência simulada. A ideia é evitar que duas execuções confirmem a mesma transação, mesmo se a tarefa rodar duas vezes. Em produção, a checagem deve ser atômica no banco, com restrição única ou transação apropriada.

from celery import Celery

app = Celery("financeiro", broker="redis://localhost:6379/0")

# Simulação didática: em produção, usar banco com constraint única e transação.
_transacoes_processadas = set()

def transacao_ja_processada(txn_id: str) -> bool:
    return txn_id in _transacoes_processadas

def marcar_como_processada(txn_id: str) -> None:
    _transacoes_processadas.add(txn_id)

@app.task(bind=True, acks_late=True)
def processar_pagamento(self, txn_id: str, valor_centavos: int) -> str:
    if transacao_ja_processada(txn_id):
        return f"Transação {txn_id} já estava processada"

    # Efeito crítico: só deve acontecer uma vez
    # Aqui ficaria a integração com adquirente, atualização no banco, etc.
    marcar_como_processada(txn_id)
    return f"Pagamento {txn_id} confirmado no valor de {valor_centavos} centavos"

Dead Letter Queue (DLQ) e isolamento de falhas recorrentes

Uma **Dead Letter Queue (DLQ)** é uma fila de “mensagens mortas” que armazena tarefas que falharam repetidamente e excederam o limite de tentativas. Essa estratégia impede que mensagens problemáticas retornem indefinidamente para a fila principal, consumindo recursos e gerando ruído operacional. Em vez disso, a falha é isolada para análise e tratamento separado. O benefício mais importante é proteger a saúde do fluxo principal de processamento.

Em brokers como SQS, DLQ é uma configuração do próprio serviço, baseada no número de recebimentos. Em outros cenários, pode ser simulada com rotas, filas específicas e políticas de reencaminhamento após exceder **max_retries**. A DLQ também melhora investigação de erros, pois concentra casos críticos que exigem correção de dados, ajuste de integração ou mudanças de regra. Em alta escala, esse isolamento reduz a chance de uma pequena fração de mensagens ruins derrubar a vazão de todo o sistema.

Observabilidade: como identificar tempestades de retry e duplicidade

Observabilidade é a capacidade de entender o estado do sistema por métricas, logs e rastreamento. Em Celery, sinais de problemas incluem aumento abrupto de retries, crescimento de profundidade de fila, tempo médio de execução subindo e consumo de CPU sem aumento proporcional de throughput útil. A duplicidade costuma aparecer como efeitos repetidos no banco, chamadas duplicadas a serviços externos e picos de carga sem causa aparente. Instrumentação adequada reduz o tempo de diagnóstico e evita decisões baseadas em suposição.

Métricas úteis incluem contagem de tarefas executadas por tipo, duração (p50, p95, p99), número de retries, taxa de falhas e tamanho da fila. Logs devem incluir identificadores como task_id, chave de deduplicação e motivo do retry, para correlacionar eventos. Em sistemas maiores, **tracing** distribuído, como **OpenTelemetry**, ajuda a seguir a linha do tempo entre produtor, broker e worker. Ferramentas de monitoramento do Celery, como **Flower**, ajudam a visualizar filas e workers, mas não substituem métricas de negócio e integridade.

Configurações recomendadas e critérios práticos de escolha

Algumas decisões se repetem na maioria dos ambientes de alta escala e funcionam como base segura. O visibility timeout deve exceder o pior tempo de execução esperado, e **acks_late** tende a ser usado quando a perda de trabalho é pior do que duplicidade. Retries devem ter backoff e jitter para reduzir sincronização de tentativas e evitar colapsos em cascata. Por fim, idempotência deve existir mesmo quando a configuração está “correta”, pois reentregas podem ocorrer por motivos fora do controle do aplicativo.

Os itens a seguir resumem as práticas mais comuns e seus objetivos, formando um checklist operacional. A lista também ajuda a separar problemas de configuração de problemas de lógica de tarefa, já que cada item atua em uma camada diferente. Em produção, essas escolhas devem considerar o tipo de broker, o perfil das tarefas e o custo do erro. Quando há tarefas heterogêneas, é comum configurar políticas diferentes por fila ou por tipo de tarefa.

• Visibility timeout: maior que o tempo máximo de tarefa, com margem para variações e lentidões externas.
• acks_late: ativado quando quedas de worker não podem causar perda silenciosa de trabalho.
• retry_backoff e retry_jitter: ativados para falhas transitórias, reduzindo tempestades de tentativas.
• max_retries: limite explícito para evitar loops infinitos e filas infladas.
• Idempotência: proteção contra efeitos duplicados usando chave de deduplicação e persistência consistente.
• DLQ: isolamento de mensagens com falhas repetidas para não degradar a fila principal.
• Monitoramento: métricas de duração, falhas, retries e profundidade de fila para detecção precoce de anomalias.

Conclusão: resiliência com previsibilidade, não redundância

Em alta escala, o objetivo não é apenas processar mais rápido, mas processar de forma previsível e segura. Ajustar **visibility timeout**, políticas de **retries** e modo de **ack** reduz a chance de reentregas inesperadas e de execução duplicada silenciosa. Mesmo assim, a garantia real de integridade vem do desenho de tarefas com **idempotência**, pois sistemas distribuídos sempre podem reexecutar mensagens. Com DLQ e observabilidade, falhas deixam de ser ruído e passam a ser eventos controláveis e rastreáveis.

Um pipeline robusto de Celery depende do alinhamento entre código, broker e operação: tempos compatíveis com a realidade das tarefas, tentativas que não causam tempestades e efeitos persistidos de forma segura. Quando esses elementos são tratados como parte da arquitetura, a fila deixa de ser um ponto frágil e se torna um mecanismo confiável de execução assíncrona. Isso reduz desperdício de recursos, melhora a consistência dos dados e mantém o sistema estável mesmo sob picos. O resultado final é resiliência de verdade, baseada em controle do ciclo de vida das mensagens.