BlogRabbitMQ

Prefetch count no RabbitMQ: por que um prefetch bem configurado é essencial em clusters de tempo real e alto throughput

Scott Sternloff

Por Scott Sternloff, Arquiteto corporativo sênior

LinkedIn · Atualizado em · 16 min de leitura

Prefetch count no RabbitMQ: por que um prefetch bem configurado é essencial em clusters de tempo real e alto throughput
On this page

De todos os parâmetros que regem o desempenho dos consumidores no RabbitMQ, o prefetch count é o que mais faz diferença — e o que mais aparece mal configurado em produção. Já entramos em inúmeros projetos corporativos de RabbitMQ em que o throughput estava limitado, a utilização dos consumidores estava travada em 60%, a memória disparava nos pods dos consumidores ou o cluster entrava em flow control com cargas que deveria absorver com facilidade — e, em uma parcela nada desprezível desses casos, a causa raiz era um prefetch definido como zero, deixado no padrão ou copiado de um tutorial escrito para outra carga de trabalho.

O prefetch é enganosamente simples. É um número inteiro. Mas ele rege o trade-off fundamental entre o throughput e a pressão de memória do consumidor, entre a latência e o overhead de acknowledgments, e entre um consumidor que consegue absorver picos e um que não consegue. Para clusters RabbitMQ de tempo real e alto throughput — do tipo que sustenta plataformas de trading, pipelines de ingestão de IoT, processadores de pagamento e qualquer coisa em que se contam mensagens por segundo e os SLAs são medidos em milissegundos —, acertar o prefetch não é opcional. É o que separa um cluster que escala de um que não escala.

O que o prefetch count faz de fato

No nível do protocolo, o prefetch count é o parâmetro basic.qos do AMQP 0-9-1. Ele diz ao broker: “não me envie mais do que N mensagens sem ack de cada vez.” Quando um consumidor se conecta e assina uma fila, o broker começa a enviar mensagens para esse consumidor até o limite do prefetch. À medida que o consumidor confirma as mensagens, o broker envia outras no lugar. O buffer de mensagens em trânsito do consumidor tem, a qualquer momento, no máximo prefetch_count mensagens.

Na prática, existem três modos de prefetch:

  • Prefetch = 0 (ilimitado). O broker envia mensagens o mais rápido que consegue. O consumidor armazena em buffer tudo o que o broker manda. Parece rápido até deixar de ser — a memória explode no consumidor, os acknowledgments atrasam e o sistema fica imprevisível sob carga.
  • Prefetch = 1. O broker envia uma mensagem, espera o ack e só então envia a próxima. É o que a maioria dos tutoriais mostra. É catastroficamente lento para cargas de alto throughput, porque cada mensagem paga o custo completo de latência de uma ida e volta.
  • Prefetch = N (valor razoável). O consumidor processa um lote de N mensagens em trânsito, o broker se mantém à frente do consumidor com um fluxo constante de reposições, e o throughput passa a ser limitado pela velocidade de processamento do consumidor, e não pelo tempo de ida e volta da rede.

O objetivo é sempre o terceiro modo. A pergunta é qual deve ser o N, e a resposta depende da sua carga de trabalho mais do que a maioria das equipes imagina.

Visão de especialista: por onde começar em cargas de alto throughput

  • Prefetch = 1. Acaba com o throughput. Você nunca vai saturar o seu consumidor. Corrija isso primeiro, sempre.
  • Prefetch = 0 (ilimitado). Funciona bem em ambiente de testes. Vira um incidente de produção na primeira vez em que o consumidor não consegue acompanhar os publishers.
  • Prefetch = 10.000. Alguém leu que “quanto maior, melhor para o throughput” e levou ao pé da letra. O consumidor armazena 10.000 mensagens em buffer, os acknowledgments atrasam, a memória sobe e, sob carga, o sistema inteiro fica imprevisível.

“Se você tem um prefetch count em zero, quer dizer que está usando o ilimitado. Isso também vai funcionar — mas, como você tem um throughput muito grande, o que eu recomendo é colocar algo como 100, 200 ou por aí.”

— Felipe Gutierrez, Senior Engineer, AceMQ (de um projeto da AceMQ que diagnosticou falhas de acknowledgment dos consumidores em um deployment corporativo de RabbitMQ de alto volume)

Essa é a nossa recomendação inicial padrão para cargas de alto throughput, e ela tem uma razão de engenharia específica. Um prefetch na faixa de 100 a 200 dá ao broker profundidade de pipeline suficiente para manter o consumidor saturado — o consumidor nunca fica esperando a próxima mensagem — sem inundar a memória do consumidor com milhares de mensagens em trânsito que ele ainda não processou. É o ponto ideal para a maioria das cargas de tempo real, e começamos por aí, ajustando para cima ou para baixo conforme o que as métricas de fato mostram.

As respostas erradas, na ordem em que mais as vemos:

Por que o prefetch importa tanto em escala

Ele controla a utilização da capacidade do consumidor

O RabbitMQ mostra na interface de gerenciamento uma métrica de “consumer capacity”, que indica a porcentagem do tempo em que o consumidor está processando mensagens ativamente, em vez de esperar que mais mensagens cheguem. Um consumidor bem ajustado opera com 100% de capacidade — está sempre trabalhando. Um consumidor com prefetch baixo demais fica em 40%, 60%, 80% de capacidade, porque passa um tempo mensurável esperando a próxima mensagem chegar pela rede. Esse tempo ocioso é throughput pelo qual você pagou e não está recebendo.

Felipe tem uma regra operacional específica para isso: se a capacidade do consumidor cair abaixo de 100%, o consumidor não está conseguindo acompanhar o fluxo de mensagens, e o desenvolvedor precisa ser avisado. Ou o prefetch está errado, ou o consumidor está processando devagar demais, ou você precisa de mais instâncias de consumidor. Em qualquer desses casos, a primeira coisa a verificar é o prefetch.

Ele rege o comportamento do flow control

O RabbitMQ tem um mecanismo de flow control que freia os publishers quando os consumidores não conseguem acompanhar. É uma válvula de segurança — impede que o broker acumule um backlog ilimitado —, mas também é um sinal de que algo está desalinhado mais acima no fluxo. Com o prefetch bem ajustado, os consumidores esvaziam a fila na velocidade máxima e o flow control raramente entra em ação. Com o prefetch baixo demais, a fila acumula sob carga, o broker entra em flow control, os publishers são bloqueados e as características de latência do sistema inteiro mudam.

Com throughput alto, a distância entre “está tudo bem” e “os produtores estão sendo bloqueados” pode ser um único valor de prefetch mal escolhido.

Ele interage com o comportamento Raft das filas de quórum

Com filas de quórum (quorum queues) — que a maioria dos deployments corporativos de RabbitMQ usa em 2026 —, as interações do prefetch ficam ainda mais importantes. Se você ainda não concluiu a sua migração para filas de quórum, a hora é agora. As filas de quórum usam o consenso Raft, o que significa que cada acknowledgment é uma gravação no log Raft em uma maioria de nós. Um prefetch de 1 em uma fila de quórum força uma ida e volta do Raft para cada mensagem, o que destrói o throughput. Um prefetch de 100 ou 200 permite que o broker agrupe os commits de acknowledgment no log Raft, o que é muito mais eficiente.

Já vimos cargas de trabalho dobrarem ou triplicarem o throughput sustentado depois de uma rodada de ajuste do prefetch em filas de quórum. A conta não tem mistério: menos commits Raft por mensagem significa mais mensagens por segundo.

Prefetch global vs individual: uma nota histórica que ainda importa

No RabbitMQ 3.x, havia dois modos distintos de prefetch que as bibliotecas de cliente podiam definir: global e individual. O prefetch global valia para todos os consumidores de um canal — se você definisse o prefetch global como 1.000 e tivesse 5 consumidores nesse canal, cada consumidor ficava, na prática, com 200. O prefetch individual valia por consumidor, então um prefetch de 1.000 significava que cada consumidor podia ter 1.000 mensagens em trânsito.

No RabbitMQ 4.x, a semântica do prefetch foi esclarecida e simplificada, mas o trade-off de fundo continua existindo. Se a sua arquitetura sobe vários consumidores em um único canal, você precisa entender se a sua biblioteca de cliente está definindo o prefetch por consumidor ou por canal, porque a quantidade efetiva de mensagens em trânsito é fundamentalmente diferente.

A recomendação prática: em sistemas de produção de alto throughput, prefira a semântica de prefetch por consumidor e um consumidor por canal. Isso dá um comportamento de memória e de throughput previsível por consumidor, que escala de forma linear quando você adiciona instâncias de consumidor. Também facilita muito a depuração de problemas de capacidade, porque o envelope de desempenho de cada consumidor é independente.

Como ajustar de fato o prefetch para a sua carga de trabalho

Não existe um valor de prefetch universalmente correto. Existe, porém, uma metodologia que leva você ao valor certo para a sua carga de trabalho específica mais rápido do que tentativa e erro.

Passo 1: comece em 100

Para qualquer carga de alto throughput no RabbitMQ que você ainda não mediu, comece com um prefetch de 100. Esse valor quase nunca é catastroficamente errado. É alto o bastante para criar um pipeline no caminho do broker até o consumidor, baixo o bastante para manter limitada a pressão de memória no consumidor, e dá uma linha de base mensurável para o ajuste.

Passo 2: meça a capacidade do consumidor sob uma carga representativa

  • Se a capacidade do consumidor estiver abaixo de 100%, o prefetch pode estar baixo demais — o consumidor está esperando mensagens.
  • Se a memória do consumidor estiver subindo e os acknowledgments estiverem atrasando, o prefetch pode estar alto demais — o consumidor está armazenando mais do que consegue processar.
  • Se a capacidade estiver em 100% e a memória estiver estável, o prefetch está correto. Não mexa.

Envie uma carga representativa pela fila e acompanhe a métrica de consumer capacity na interface de gerenciamento do RabbitMQ. Acompanhe também o uso de memória do consumidor. Para visibilidade no nível do cluster, veja o nosso guia de monitoramento do RabbitMQ no Kubernetes. Você está procurando três condições:

Passo 3: ajuste em incrementos significativos

Se precisar aumentar, tente 200 e depois 500. Não pule de 100 para 10.000 — a relação entre prefetch e throughput não é linear. Cada duplicação deve mostrar uma melhora mensurável de throughput no início, depois retornos decrescentes e, por fim, retornos negativos, quando o consumidor começa a sofrer com o próprio buffer.

Passo 4: leve em conta o tamanho das mensagens

Um prefetch de 200 com mensagens de 1KB representa 200KB de memória em trânsito por consumidor. Um prefetch de 200 com mensagens de 1MB representa 200MB de memória em trânsito por consumidor. Se as suas mensagens são grandes — e em pipelines de tempo real muitas vezes são —, o prefetch precisa ser menor do que no caso de mensagens pequenas. Calcule a memória máxima em trânsito como prefetch_count × p99_message_size e dimensione a memória do consumidor de acordo. Não se esqueça desse cálculo em ambientes com tamanhos de mensagem heterogêneos.

Passo 5: teste nos limites de falha

O valor de prefetch certo é aquele que tem bom desempenho sob carga em regime estável E durante cenários de recuperação. Simule a queda de um consumidor enquanto a fila tem mensagens acumuladas. Quando o consumidor substituto sobe, ele esvazia o backlog de forma limpa, na taxa esperada? Ou a configuração de prefetch dele o deixa sem mensagens ou o inunda? Valores de prefetch que parecem bons em regime estável podem se comportar mal durante um failover, que é justamente quando você precisa que eles se comportem corretamente.

A armadilha do tamanho das mensagens: por que o prefetch sozinho não basta

Uma das armadilhas operacionais mais comuns que vemos em deployments de RabbitMQ de alto throughput é tratar o prefetch como o único botão de ajuste quando o problema real é o tamanho das mensagens. O RabbitMQ é um message broker, não um banco de dados — e também não é um sistema de transferência de arquivos.

Já vimos deployments de RabbitMQ em produção em que o operador reclamava que o throughput estava “misteriosamente” limitado a uma fração da taxa esperada, só para descobrir, na investigação, que a aplicação estava enviando PDFs de vários megabytes, clipes de vídeo ou snapshots serializados de banco de dados como payload das mensagens. Nenhum ajuste de prefetch resolve isso. O broker está fazendo o que pediram — só que pediram algo que ele não deveria fazer.

A regra de arquitetura é: mantenha as mensagens do RabbitMQ pequenas. Uma revisão de arquitetura do RabbitMQ pode ajudar a identificar onde o tamanho dos payloads está prejudicando o seu throughput. Se você precisa mover um payload grande pelo sistema, grave-o em object storage e envie uma referência pelo RabbitMQ. Mensagens de 4KB passam por um cluster ordens de grandeza mais rápido do que mensagens de 4MB, mesmo com configurações de prefetch idênticas, porque:

  • Mensagens menores consomem menos banda de rede por mensagem.
  • Mensagens menores consomem menos memória nos buffers do broker e do consumidor.
  • Mensagens menores são persistidas em disco mais rápido nas filas de quórum.
  • Mensagens menores são replicadas mais rápido para os followers do Raft.

Isso não é, a rigor, um problema de prefetch. Mas qualquer conversa sobre ajustar o prefetch em sistemas de tempo real e alto throughput precisa incluir a auditoria de tamanho, porque ajustar o prefetch em um pipeline de mensagens de 4MB é otimizar a camada errada.

Quando revisar o prefetch

O prefetch não é um parâmetro para configurar e esquecer. Revise a sua configuração de prefetch quando:

  • Os requisitos de throughput mudarem. Um crescimento de 10x no volume de mensagens muitas vezes significa que um prefetch que funcionava na escala antiga está errado na nova.
  • A distribuição de tamanhos das mensagens mudar. Novos recursos da aplicação que enviam mensagens maiores mudam a conta da memória.
  • Você migrar para filas de quórum. O overhead dos commits Raft muda o valor ideal de prefetch, geralmente para cima.
  • Você mudar a arquitetura dos consumidores. Passar de N consumidores em um canal para N consumidores, cada um no próprio canal, muda completamente a conta do prefetch.
  • Você vir a capacidade dos consumidores abaixo de 100% sob carga. Esse é o sinal mais claro de que algo no seu pipeline de prefetch + consumidor + broker está desalinhado.
  • Você vir o flow control entrando em ação com cargas que não deveriam acioná-lo. O flow control é o broker avisando que os consumidores não estão dando conta. O prefetch é um dos primeiros lugares a olhar.

Resumo prático

O prefetch é o parâmetro de ajuste do lado do consumidor com maior alavancagem no RabbitMQ. Errar nele com throughput alto aparece como limites de capacidade misteriosos, comportamento imprevisível da memória, eventos de flow control com cargas que não deveriam causá-los e chamados de suporte dizendo que “o RabbitMQ está lento” sem apontar uma causa específica.

Acertar nele não aparece em nada, que é exatamente o que você quer: consumidores com 100% de capacidade, memória estável, latência limitada e um throughput que escala de forma previsível à medida que você adiciona instâncias de consumidor.

Se você está colocando no ar hoje uma nova carga de tempo real no RabbitMQ e precisa de um ponto de partida sem tempo para um ajuste completo: prefetch = 100, por consumidor, um consumidor por canal. Meça a capacidade dos consumidores, ajuste a partir daí e audite o tamanho das suas mensagens antes de mexer em qualquer outro parâmetro. Essa única recomendação, aplicada de forma consistente, evita boa parte dos problemas de desempenho que somos chamados para diagnosticar.

Para cargas de trabalho que levam o sistema ao limite — centenas de milhares de mensagens por segundo, SLAs abaixo de 10 ms, durabilidade de nível financeiro —, o ajuste fica mais sutil, e as interações com filas de quórum, Raft e a arquitetura dos consumidores exigem mais atenção. Mas o ponto de partida é o mesmo, e a metodologia é a mesma: comece em 100, meça, ajuste e mantenha as suas mensagens pequenas.

Está ajustando um cluster RabbitMQ de alto throughput e bateu no teto?

A equipe de engenharia da AceMQ já ajustou clusters RabbitMQ rodando nos extremos — plataformas de trading, sistemas de pagamento, pipelines globais da área da saúde e ambientes de analytics em tempo real medidos em centenas de milhares de mensagens por segundo. O prefetch é só uma peça do quebra-cabeça. Se o seu cluster está limitado abaixo de onde deveria estar, conseguimos rastrear o gargalo — broker, consumidor, tipo de fila, rede, disco — e levar você de volta a uma escala linear.

Se você está construindo uma nova carga de alto throughput e quer acertar a arquitetura e o ajuste desde o início, ou tem um cluster existente que não está entregando o desempenho que deveria, fale com a nossa equipe sobre uma avaliação de desempenho. Fazemos consultoria em RabbitMQ, suporte comercial para RabbitMQ e troubleshooting aprofundado de RabbitMQ para clientes corporativos no mundo todo — é só isso que fazemos.

Prefetch count: as respostas curtas

O prefetch count é o número máximo de mensagens sem ack que o RabbitMQ envia para um consumidor (ou um canal) antes de parar e esperar pelos acks. Todo o resto decorre desse único limite.

Por onde começar. Para a maioria das cargas de trabalho, defina o prefetch entre 10 e 30 e meça. Use 1 quando você precisar de ordenação estrita entre consumidores ou quando cada mensagem levar segundos para ser processada, porque qualquer valor maior estaciona trabalho em um consumidor que não consegue chegar até ele. Suba para a faixa de 100 a 300 apenas quando os consumidores forem rápidos e idempotentes e um teste de carga tiver confirmado que o host do consumidor tem folga de memória. Maior não é mais rápido depois que o consumidor está saturado; só transfere o backlog do broker para o cliente.

Por que o 0 causa mais problemas. Um prefetch de 0 significa ilimitado. O broker envia todas as mensagens prontas para o primeiro consumidor com um canal aberto, então um consumidor monopoliza a fila enquanto os outros ficam parados. A mesma configuração está por trás da maior parte da pressão de memória do lado do consumidor que nos chamam para resolver: uma fila se esvazia em um único processo que não consegue enviar acks rápido o bastante, e o processo entra em swap ou é encerrado. Se uma fila parece vazia, mas o throughput está ruim e um consumidor está cravado em 100% de CPU, verifique primeiro se o prefetch é 0.

O prefetch só existe para consumidores com ack manual. Com auto-ack, o broker trata uma mensagem como confirmada no momento em que ela é enviada, então nunca há nada pendente para contar contra o limite. Definir um prefetch em um consumidor com auto-ack não faz nada.

Filas de quórum e streams não são filas clássicas. As filas de quórum respeitam o prefetch, mas também controlam um contador de entregas por mensagem e aplicam um delivery-limit (20 por padrão no 4.x). Um consumidor com um prefetch grande que cai devolve todas as mensagens sem ack com o contador de entregas incrementado, então algumas reinicializações podem mandar para dead-letter mensagens que nunca foram problemáticas. Os streams são diferentes de novo. No protocolo de streams, o controle de fluxo é baseado em crédito, e não em prefetch. Via AMQP 0-9-1, um consumidor de stream precisa definir um prefetch diferente de zero e usar acks manuais, e o ack não apaga nada; ele devolve crédito para que o broker envie mais. Veja filas clássicas vs filas de quórum para a comparação completa.

Três motivos pelos quais o prefetch "não funciona" em um teste de carga. Primeiro, o consumidor está em auto-ack e a configuração é ignorada. Segundo, a flag global: no RabbitMQ, global=false limita cada consumidor e global=true limita o canal inteiro, e algumas bibliotecas de cliente usam um padrão diferente ou interpretam essa flag de outra forma. Terceiro, o framework do cliente aplica o próprio padrão (muitas vezes 1, às vezes 250) depois que o seu código roda, ou em um canal diferente daquele que você configurou. Verifique o valor efetivo com rabbitmqctl list_consumers, em vez de confiar no código.

O prefetch é o quinto de dez padrões do guia de confiabilidade do RabbitMQ e o sétimo passo do guia de clustering e dimensionamento, que cobre a metade do lado do cluster da mesma questão de throughput.

Perguntas frequentes

Qual é um bom valor de prefetch count no RabbitMQ?

Comece com 10 a 30 para consumidores típicos e ajuste a partir daí com um teste de carga. Use 1 para tarefas demoradas ou quando a ordenação entre consumidores importa. Reserve de 100 a 300 para consumidores rápidos e idempotentes, quando você tiver medido que o host do cliente tem folga de memória para tantas mensagens em trânsito. Nunca deixe em 0 em produção; isso significa ilimitado e é, de longe, a causa mais comum de um consumidor monopolizar uma fila enquanto os outros ficam ociosos. O número certo é o menor valor que mantém os seus consumidores ocupados.

Por que o prefetch count do meu RabbitMQ não está funcionando?

Três causas cobrem quase todos os casos que investigamos. O consumidor está usando auto-ack, então o prefetch é totalmente ignorado. A flag global está configurada ao contrário do que você espera, então o limite vale por canal em vez de por consumidor, ou vice-versa. Ou o framework do cliente define o próprio padrão depois que o seu código roda, ou em um canal diferente daquele que você configurou. Confirme o valor efetivo com rabbitmqctl list_consumers. Se o comportamento continuar estranho, os 10 principais problemas de troubleshooting do RabbitMQ cobrem os modos de falha relacionados.

O prefetch count vale para filas de quórum e streams?

As filas de quórum (quorum queues) respeitam o prefetch exatamente como as filas clássicas, com um acréscimo: cada reentrega incrementa um contador de entregas por mensagem e, quando ele passa do delivery-limit, a mensagem vai para dead-letter ou é descartada. Um consumidor que cai com um prefetch grande empurra muitas mensagens em direção a esse limite de uma só vez, então mantenha o prefetch moderado em filas de quórum. Streams via AMQP 0-9-1 exigem um prefetch diferente de zero e acks manuais, mas o ack apenas devolve crédito; ele não remove a mensagem. No protocolo nativo de streams, o controle de fluxo é baseado em crédito, e o prefetch simplesmente não é o modelo.

O prefetch deve ser definido por canal ou por consumidor?

Por consumidor, em quase todos os casos. No RabbitMQ, global=false (o padrão na maioria dos clientes) aplica o limite a cada consumidor de forma independente, que é o que as pessoas esperam e o que torna o ajuste previsível. global=true aplica um único limite compartilhado a todos os consumidores do canal, o que só é útil quando vários consumidores em um canal precisam dividir um orçamento fixo de mensagens em trânsito. Se você definir os dois, o broker aplica os dois. Quando assumimos um ambiente RabbitMQ 3.8 a 4.x em suporte gerenciado, verificar essa flag é uma das primeiras coisas que fazemos, porque ela explica um número surpreendente de reclamações de throughput.

Scott Sternloff

Autor

Scott SternloffArquiteto corporativo sênior

Arquiteto corporativo sênior na AceMQ. Escreve a cobertura técnica deste blog: arquitetura, clustering e migrações de RabbitMQ, Kafka e Redis.

Consulta gratuita

Um olhar especializado sobre seu cluster RabbitMQ

Seja para resolver um incidente em produção, planejar uma migração ou ter uma segunda opinião sobre sua arquitetura, nossa equipe está pronta. Sem discurso de vendas, só respostas.

Envie um e-mail