On this page
De todos os parâmetros de ajuste que regem o desempenho dos consumidores do RabbitMQ, o prefetch count é o que mais faz a diferença — e o que aparece mais vezes mal configurado em produção. Já entrámos em inúmeros projetos empresariais de RabbitMQ em que o débito estava limitado, a utilização dos consumidores estava presa nos 60%, a memória disparava nos pods dos consumidores ou o cluster entrava em flow control com cargas que devia absorver com facilidade — e, numa percentagem nada desprezável desses casos, a causa raiz era um prefetch definido a zero, deixado na predefinição ou copiado de um tutorial escrito para outra carga de trabalho.
O prefetch é enganadoramente simples. É um número inteiro. Mas rege o compromisso fundamental entre o débito do consumidor e a pressão de memória no consumidor, entre a latência e o overhead dos acknowledgments, e entre um consumidor capaz de absorver picos e um que não é. Em clusters RabbitMQ de tempo real e alto débito — os que suportam plataformas de trading, pipelines de ingestão de IoT, processadores de pagamentos e tudo o que conte mensagens por segundo e meça SLAs em milissegundos —, acertar no prefetch não é opcional. É o que distingue um cluster que escala de um que não escala.
O que faz realmente o prefetch count
Ao nível do protocolo, o prefetch count é o parâmetro basic.qos do AMQP 0-9-1. Diz ao broker: “não me envies mais do que N mensagens sem acknowledgment de cada vez.” Quando um consumidor se liga e subscreve uma fila, o broker começa a enviar mensagens a esse consumidor até ao limite do prefetch. À medida que o consumidor confirma as mensagens, o broker envia outras para as substituir. O buffer de mensagens em trânsito do consumidor tem, em qualquer momento, no máximo prefetch_count mensagens.
Na prática, existem três modos de prefetch:
- Prefetch = 0 (ilimitado). O broker envia mensagens tão depressa quanto consegue. O consumidor guarda em buffer tudo o que o broker envia. Parece rápido até deixar de o ser — a memória dispara no consumidor, os acknowledgments atrasam-se e o sistema torna-se imprevisível sob carga.
- Prefetch = 1. O broker envia uma mensagem, espera pelo ack e só depois envia a seguinte. É o que a maioria dos tutoriais mostra. É catastroficamente lento para cargas de alto débito, 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 mantém-se à frente do consumidor com um fluxo constante de substituições, e o débito fica 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 questão é qual deve ser o valor de N, e a resposta depende da sua carga de trabalho mais do que a maioria das equipas imagina.
Visão de especialista: por onde começar em cargas de alto débito
- Prefetch = 1. Arruína o débito. Nunca vai conseguir saturar o consumidor. Corrija isto primeiro, sempre.
- Prefetch = 0 (ilimitado). Funciona bem num ambiente de testes. Torna-se 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 mais alto, melhor para o débito” e levou-o à letra. O consumidor guarda 10 000 mensagens em buffer, os acknowledgments atrasam-se, a memória sobe e, sob carga, o sistema inteiro torna-se imprevisível.
“Se tem o prefetch count a zero, isso significa que está a usar o ilimitado. Também vai funcionar — mas, como tem um débito muito elevado, o que eu recomendo é pôr qualquer coisa como 100, 200 ou à volta disso.”
— Felipe Gutierrez, Senior Engineer, AceMQ (de um projeto da AceMQ que diagnosticou falhas de acknowledgment dos consumidores numa implementação empresarial de RabbitMQ de grande volume)
Esta é a nossa recomendação inicial habitual para cargas de alto débito, e assenta numa razão de engenharia concreta. Um prefetch entre 100 e 200 dá ao broker profundidade de pipeline suficiente para manter o consumidor saturado — o consumidor nunca fica à espera da mensagem seguinte — sem inundar a memória do consumidor com milhares de mensagens em trânsito que ainda não processou. É o ponto ideal para a maioria das cargas de tempo real; começamos por aí e ajustamos para cima ou para baixo consoante o que as métricas efetivamente mostram.
As respostas erradas, pela ordem em que mais as vemos:
Porque é que o prefetch importa tanto em escala
Controla a utilização da capacidade do consumidor
O RabbitMQ apresenta na interface de gestão uma métrica de “consumer capacity”, que indica a percentagem do tempo em que o consumidor está a processar mensagens ativamente, em vez de estar à espera de que cheguem mais. Um consumidor bem ajustado funciona a 100% de capacidade — está sempre a trabalhar. Um consumidor com o prefetch demasiado baixo fica nos 40%, 60%, 80% de capacidade, porque passa um tempo mensurável à espera de que a mensagem seguinte chegue pela rede. Esse tempo inativo é débito pelo qual pagou e que não está a obter.
O Felipe tem uma regra operacional específica para isto: se a capacidade do consumidor descer abaixo dos 100%, o consumidor não está a conseguir acompanhar o fluxo de mensagens e o programador tem de ser avisado. Ou o prefetch está errado, ou o consumidor está a processar demasiado devagar, ou são necessárias mais instâncias de consumidor. Em qualquer destes casos, a primeira coisa a verificar é o prefetch.
Rege o comportamento do flow control
O RabbitMQ tem um mecanismo de flow control que trava os publishers quando os consumidores não conseguem acompanhar. É uma válvula de segurança — impede que o broker acumule um backlog sem limites —, mas é também um sinal de que algo a montante está desalinhado. Com o prefetch bem ajustado, os consumidores esvaziam a fila à velocidade máxima e o flow control raramente entra em ação. Com o prefetch demasiado baixo, a fila acumula sob carga, o broker entra em flow control, os publishers ficam bloqueados e as características de latência de todo o sistema mudam.
Com débito elevado, a distância entre “está tudo bem” e “os produtores estão a ser bloqueados” pode ser um único valor de prefetch mal escolhido.
Interage com o comportamento Raft das filas de quórum
Com as filas de quórum (quorum queues) — que a maioria das implementações empresariais de RabbitMQ usa em 2026 —, as interações do prefetch tornam-se ainda mais determinantes. Se ainda não concluiu a migração para filas de quórum, este é o momento. As filas de quórum usam o consenso Raft, o que significa que cada acknowledgment é uma escrita no log Raft numa maioria de nós. Um prefetch de 1 numa fila de quórum obriga a uma ida e volta do Raft por cada mensagem, o que destrói o débito. Um prefetch de 100 ou 200 permite ao broker agrupar os commits de acknowledgment no log Raft, o que é muitíssimo mais eficiente.
Já vimos cargas de trabalho duplicarem ou triplicarem o débito sustentado depois de uma ronda de ajuste do prefetch em filas de quórum. As contas não têm nada de subtil: menos commits Raft por mensagem significam mais mensagens por segundo.
Prefetch global vs individual: uma nota histórica que continua a importar
No RabbitMQ 3.x, havia dois modos de prefetch distintos que as bibliotecas cliente podiam definir: global e individual. O prefetch global aplicava-se a todos os consumidores de um canal — se definisse o prefetch global como 1 000 e tivesse 5 consumidores nesse canal, cada consumidor ficava, na prática, com 200. O prefetch individual aplicava-se por consumidor, pelo que 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 clarificada e simplificada, mas o compromisso de fundo mantém-se. Se a sua arquitetura arranca vários consumidores num único canal, tem de perceber se a biblioteca cliente está a definir o prefetch por consumidor ou por canal, porque o número efetivo de mensagens em trânsito é fundamentalmente diferente.
A recomendação prática: em sistemas de produção de alto débito, prefira a semântica de prefetch por consumidor e um consumidor por canal. Isso dá um comportamento de memória e de débito previsível por consumidor, que escala de forma linear quando se acrescentam instâncias de consumidor. Também simplifica muito a depuração de problemas de capacidade, porque o envelope de desempenho de cada consumidor é independente.
Como ajustar realmente o prefetch à sua carga de trabalho
Não existe um valor de prefetch universalmente correto. Existe, no entanto, uma metodologia que o leva ao valor certo para a sua carga de trabalho específica mais depressa do que andar a adivinhar.
Passo 1: comece em 100
Para qualquer carga de alto débito no RabbitMQ que ainda não tenha medido, comece com um prefetch de 100. Este valor quase nunca está catastroficamente errado. É suficientemente alto para criar um pipeline no caminho entre o broker e o consumidor, suficientemente baixo para manter limitada a pressão de memória no consumidor, e dá-lhe uma base mensurável a partir da qual ajustar.
Passo 2: meça a capacidade do consumidor sob uma carga representativa
- Se a capacidade do consumidor estiver abaixo dos 100%, o prefetch pode estar demasiado baixo — o consumidor está à espera de mensagens.
- Se a memória do consumidor estiver a subir e os acknowledgments a atrasar-se, o prefetch pode estar demasiado alto — o consumidor está a guardar mais do que consegue processar.
- Se a capacidade estiver nos 100% e a memória estável, o prefetch está correto. Não lhe mexa.
Faça passar uma carga representativa pela fila e acompanhe a métrica de consumer capacity na interface de gestão do RabbitMQ. Acompanhe também a utilização de memória do consumidor. Para visibilidade ao nível do cluster, consulte o nosso guia de monitorização do RabbitMQ no Kubernetes. Procura três situações:
Passo 3: ajuste em incrementos significativos
Se precisar de subir, experimente 200 e depois 500. Não salte de 100 para 10 000 — a relação entre prefetch e débito não é linear. Cada duplicação deve mostrar, de início, uma melhoria mensurável do débito, depois rendimentos decrescentes e, por fim, rendimentos negativos, quando o consumidor começa a ter dificuldades com o seu próprio buffer.
Passo 4: tenha em conta a dimensão das mensagens
Um prefetch de 200 com mensagens de 1KB equivale a 200KB de memória em trânsito por consumidor. Um prefetch de 200 com mensagens de 1MB equivale a 200MB de memória em trânsito por consumidor. Se as suas mensagens são grandes — e nos pipelines de tempo real são-no muitas vezes —, o prefetch tem de ser mais baixo 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 em conformidade. Não se esqueça deste cálculo em ambientes com dimensões de mensagem heterogéneas.
Passo 5: teste nos limites de falha
O valor de prefetch certo é aquele que se porta bem 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 arranca, esvazia o backlog de forma limpa, ao ritmo esperado? Ou a sua configuração de prefetch deixa-o sem mensagens ou inunda-o? Valores de prefetch que parecem bons em regime estável podem comportar-se mal durante um failover, que é precisamente quando precisa que se comportem corretamente.
A armadilha da dimensão das mensagens: porque é que o prefetch, por si só, não basta
Uma das armadilhas operacionais mais comuns que vemos em implementações de RabbitMQ de alto débito é tratar o prefetch como o único botão de ajuste quando o verdadeiro problema é a dimensão das mensagens. O RabbitMQ é um message broker, não uma base de dados — e também não é um sistema de transferência de ficheiros.
Já vimos implementações de RabbitMQ em produção em que o operador se queixava de que o débito estava “misteriosamente” limitado a uma fração do ritmo esperado, para depois se descobrir, na investigação, que a aplicação enviava PDFs de vários megabytes, clipes de vídeo ou snapshots serializados de bases de dados como payload das mensagens. Nenhum ajuste de prefetch resolve isso. O broker está a fazer o que lhe pediram — só que lhe pediram algo que não devia fazer.
A regra de arquitetura é: mantenha as mensagens do RabbitMQ pequenas. Uma revisão de arquitetura do RabbitMQ pode ajudar a identificar onde a dimensão dos payloads está a prejudicar o débito. Se precisa de fazer passar um payload grande pelo sistema, escreva-o num object store e envie uma referência pelo RabbitMQ. Mensagens de 4KB atravessam um cluster ordens de grandeza mais depressa do que mensagens de 4MB, mesmo com configurações de prefetch idênticas, porque:
- As mensagens mais pequenas consomem menos largura de banda de rede por mensagem.
- As mensagens mais pequenas consomem menos memória nos buffers do broker e do consumidor.
- As mensagens mais pequenas são persistidas em disco mais depressa nas filas de quórum.
- As mensagens mais pequenas são replicadas mais depressa para os followers do Raft.
Em rigor, isto não é um problema de prefetch. Mas qualquer conversa sobre o ajuste do prefetch em sistemas de tempo real e alto débito tem de incluir a auditoria da dimensão das mensagens, porque ajustar o prefetch num pipeline de mensagens de 4MB é otimizar a camada errada.
Quando rever o prefetch
O prefetch não é um parâmetro para configurar e esquecer. Reveja a configuração de prefetch quando:
- Os requisitos de débito mudarem. Um crescimento de 10x no volume de mensagens significa muitas vezes que um prefetch adequado à escala antiga está errado na nova.
- A distribuição da dimensão das mensagens se alterar. Novas funcionalidades da aplicação que enviam mensagens maiores mudam as contas da memória.
- Migrar para filas de quórum. O overhead dos commits Raft altera o valor ideal de prefetch, normalmente para cima.
- Alterar a arquitetura dos consumidores. Passar de N consumidores num canal para N consumidores, cada um no seu próprio canal, muda por completo as contas do prefetch.
- Vir a capacidade dos consumidores abaixo dos 100% sob carga. É o sinal mais claro de que algo no seu pipeline de prefetch + consumidor + broker está desalinhado.
- Vir o flow control a entrar em ação com cargas que não o deviam acionar. O flow control é o broker a dizer-lhe que os consumidores não estão a dar conta. O prefetch é um dos primeiros sítios onde procurar.
Conclusão prática
O prefetch é o parâmetro de ajuste do lado do consumidor com maior efeito de alavanca no RabbitMQ. Errar nele com débito elevado traduz-se em limites de capacidade misteriosos, comportamento imprevisível da memória, eventos de flow control com cargas que não os deviam provocar e pedidos de suporte a dizer que “o RabbitMQ está lento” sem apontar uma causa concreta.
Acertar nele não se nota, que é exatamente o que se pretende: consumidores a 100% de capacidade, memória estável, latência limitada e um débito que escala de forma previsível à medida que se acrescentam instâncias de consumidor.
Se está hoje a pôr em funcionamento 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 a dimensão das mensagens antes de mexer em qualquer outro parâmetro. Esta única recomendação, aplicada de forma consistente, evita uma boa parte dos problemas de desempenho que somos chamados a diagnosticar.
Para cargas de trabalho que levam o sistema ao limite — centenas de milhares de mensagens por segundo, SLAs inferiores a 10 ms, durabilidade de nível financeiro —, o ajuste torna-se mais subtil, e as interações com as filas de quórum, o Raft e a arquitetura dos consumidores exigem mais atenção. Mas o ponto de partida é o mesmo, e a metodologia também: comece em 100, meça, ajuste e mantenha as mensagens pequenas.
Está a ajustar um cluster RabbitMQ de alto débito e bateu no teto?
A equipa de engenharia da AceMQ já ajustou clusters RabbitMQ a funcionar nos extremos — plataformas de trading, sistemas de pagamentos, pipelines globais na área da saúde e ambientes de analytics em tempo real medidos em centenas de milhares de mensagens por segundo. O prefetch é apenas uma peça do puzzle. Se o seu cluster está limitado abaixo do que devia, conseguimos localizar o estrangulamento — broker, consumidor, tipo de fila, rede, disco — e repor o escalonamento linear.
Se está a construir uma nova carga de alto débito e quer acertar na arquitetura e no ajuste desde o início, ou tem um cluster existente que não está a render o que devia, fale com a nossa equipa sobre uma avaliação de desempenho. Fazemos consultoria em RabbitMQ, suporte comercial para RabbitMQ e resolução aprofundada de problemas de RabbitMQ para clientes empresariais em todo o mundo — é só isto que fazemos.
Prefetch count: as respostas curtas
O prefetch count é o número máximo de mensagens sem acknowledgment que o RabbitMQ envia a um consumidor (ou a um canal) antes de parar e esperar pelos acks. Tudo o resto decorre deste ú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 precisar de ordenação estrita entre consumidores ou quando cada mensagem demorar segundos a processar, porque qualquer valor superior deixa trabalho parado num consumidor que não consegue chegar a ele. Suba para o intervalo 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 margem de memória. Maior não é mais rápido depois de o consumidor estar saturado; apenas transfere o backlog do broker para o cliente.
Porque é 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, pelo que 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 a resolver: uma fila esvazia-se para um único processo que não consegue enviar acks com rapidez suficiente, e o processo entra em swap ou é terminado. Se uma fila parece vazia, mas o débito é fraco e um consumidor está cravado nos 100% de CPU, verifique primeiro se o prefetch está a 0.
O prefetch só existe para consumidores com ack manual. Com auto-ack, o broker considera uma mensagem confirmada no momento em que a envia, pelo que nunca há nada pendente que conte para o limite. Definir um prefetch num consumidor com auto-ack não tem qualquer efeito.
As filas de quórum e os streams não são filas clássicas. As filas de quórum respeitam o prefetch, mas também mantêm um contador de entregas por mensagem e aplicam um delivery-limit (20 por predefinição no 4.x). Um consumidor com um prefetch elevado que falhe devolve todas as mensagens sem ack com o contador de entregas incrementado, pelo que alguns reinícios podem enviar para dead-letter mensagens que nunca foram problemáticas. Os streams voltam a ser diferentes. No protocolo de streams, o controlo de fluxo baseia-se em crédito, e não em prefetch. Através de AMQP 0-9-1, um consumidor de stream tem de definir um prefetch diferente de zero e usar acks manuais, e o ack não apaga nada; devolve crédito para que o broker envie mais. Consulte filas clássicas vs filas de quórum para a comparação completa.
Três razões pelas quais o prefetch "não funciona" num 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 cliente usam outra predefinição ou interpretam essa flag de forma diferente. Terceiro, a framework cliente aplica a sua própria predefinição (muitas vezes 1, por vezes 250) depois de o seu código correr, ou num canal diferente daquele que 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 fiabilidade do RabbitMQ e o sétimo passo do guia de clustering e dimensionamento, que trata a metade da mesma questão de débito que diz respeito ao cluster.
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 é importante. Reserve 100 a 300 para consumidores rápidos e idempotentes, depois de medir que o host cliente tem margem de memória para tantas mensagens em trânsito. Nunca o deixe a 0 em produção; isso significa ilimitado e é, de longe, a causa mais comum de um consumidor monopolizar uma fila enquanto os outros ficam parados. O número certo é o valor mais baixo que mantém os consumidores ocupados.
Porque é que o prefetch count do meu RabbitMQ não funciona?
Três causas explicam quase todos os casos que investigámos. O consumidor está a usar auto-ack, pelo que o prefetch é totalmente ignorado. A flag global está definida ao contrário do que se espera, pelo que o limite se aplica por canal em vez de por consumidor, ou vice-versa. Ou a framework cliente define a sua própria predefinição depois de o seu código correr, ou num canal diferente daquele que configurou. Confirme o valor efetivo com rabbitmqctl list_consumers. Se o comportamento continuar estranho, os 10 problemas mais comuns do RabbitMQ e como evitá-los abordam os modos de falha relacionados.
O prefetch count aplica-se às filas de quórum e aos 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 este ultrapassa o delivery-limit, a mensagem segue para dead-letter ou é descartada. Um consumidor que falha com um prefetch elevado empurra muitas mensagens para esse limite de uma só vez, por isso mantenha o prefetch moderado nas filas de quórum. Os streams através de AMQP 0-9-1 exigem um prefetch diferente de zero e acks manuais, mas o ack apenas devolve crédito, não remove a mensagem. No protocolo nativo de streams, o controlo de fluxo baseia-se 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 (a predefiniçã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 partilhado a todos os consumidores do canal, o que só é útil quando vários consumidores num canal têm de partilhar um orçamento fixo de mensagens em trânsito. Se definir ambos, o broker aplica ambos. Quando assumimos um ambiente RabbitMQ 3.8 a 4.x em suporte gerido, verificar esta flag é uma das primeiras coisas que fazemos, porque explica um número surpreendente de queixas de débito.
Guias, comparações e estudos

