BlogueRabbitMQ

Prefetch count no RabbitMQ: porque é que um prefetch bem configurado é crítico em clusters de tempo real e alto débito

Scott Sternloff

Por Scott Sternloff, Arquiteto empresarial sénior

LinkedIn · Atualizado a · 16 min de leitura

Prefetch count no RabbitMQ: porque é que um prefetch bem configurado é crítico em clusters de tempo real e alto débito
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.

Scott Sternloff

Autor

Scott SternloffArquiteto empresarial sénior

Arquiteto empresarial sénior na AceMQ. Escreve aqui os conteúdos técnicos: arquitetura, clustering e migrações de RabbitMQ, Kafka e Redis.

Consulta gratuita

Obtenha uma análise especializada de cluster RabbitMQ

Quer esteja a resolver um incidente em produção, a planear uma migração ou queira uma segunda opinião sobre a sua arquitetura, a nossa equipa está pronta. Sem discursos de vendas, apenas respostas.

Enviar e-mail