BlogRabbitMQ

RabbitMQ prefetch count: perché un prefetch ben configurato è fondamentale per i cluster real-time ad alto throughput

Scott Sternloff

Di Scott Sternloff, Enterprise Architect senior

LinkedIn · Aggiornato il · 16 min di lettura

RabbitMQ prefetch count: perché un prefetch ben configurato è fondamentale per i cluster real-time ad alto throughput
On this page

Fra tutti i parametri di tuning che governano le prestazioni dei consumer RabbitMQ, il prefetch count è quello che fa la differenza più grande, ed è anche quello configurato male con più costanza in produzione. Siamo intervenuti in innumerevoli progetti RabbitMQ enterprise in cui il throughput era limitato, l'utilizzo dei consumer era fermo al 60%, la memoria sui pod dei consumer aveva picchi improvvisi o il cluster entrava in flow control con carichi che avrebbe dovuto assorbire senza difficoltà; e in una percentuale non trascurabile di quei casi la causa principale era un prefetch impostato a zero, lasciato al default o copiato da un tutorial scritto per un workload diverso.

Il prefetch è solo in apparenza semplice. È un numero intero. Ma governa il compromesso fondamentale tra throughput e pressione sulla memoria del consumer, tra latenza e overhead degli acknowledgment, e tra un consumer in grado di assorbire i picchi e uno che non lo è. Per i cluster RabbitMQ real-time ad alto throughput, come quelli che supportano piattaforme di trading, pipeline di ingestione IoT, processori di pagamento e qualsiasi altro sistema in cui si contano i messaggi al secondo e gli SLA si misurano in millisecondi, impostare correttamente il prefetch non è facoltativo. È ciò che separa un cluster che scala da uno che non scala.

Che cosa fa davvero il prefetch count

A livello di protocollo, il prefetch count è il parametro basic.qos di AMQP 0-9-1. Dice al broker: “non inviarmi più di N messaggi non confermati alla volta”. Quando un consumer si connette e si sottoscrive a una coda, il broker inizia a inviargli messaggi fino al limite di prefetch. Man mano che il consumer conferma i messaggi, il broker ne invia di nuovi. In qualsiasi momento, il buffer dei messaggi in transito del consumer contiene al massimo prefetch_count messaggi.

In pratica esistono tre modalità di prefetch:

  • Prefetch = 0 (illimitato). Il broker invia messaggi alla massima velocità possibile. Il consumer mette in buffer tutto ciò che il broker invia. Sembra veloce finché non lo è più: la memoria del consumer esplode, gli acknowledgment restano indietro e sotto carico il sistema diventa imprevedibile.
  • Prefetch = 1. Il broker invia un messaggio, attende l'ack, poi invia il successivo. È ciò che mostra la maggior parte dei tutorial. Per i workload ad alto throughput è disastrosamente lento, perché ogni singolo messaggio paga l'intero costo di latenza di un round-trip.
  • Prefetch = N (valore ragionevole). Il consumer elabora un gruppo di N messaggi in transito, il broker resta un passo avanti al consumer con un flusso costante di messaggi sostitutivi e il throughput è limitato dalla velocità di elaborazione del consumer anziché dal tempo di round-trip della rete.

L'obiettivo è sempre la terza modalità. La domanda è quale debba essere N, e la risposta dipende dal workload più di quanto la maggior parte dei team immagini.

Il parere dell'esperto: da dove partire per i workload ad alto throughput

  • Prefetch = 1. Uccide il throughput. Non riuscirete mai a saturare il consumer. Correggete questo per primo, sempre.
  • Prefetch = 0 (illimitato). Funziona bene in un ambiente di test. Diventa un incidente di produzione la prima volta che il consumer non riesce a stare al passo con i publisher.
  • Prefetch = 10.000. Qualcuno ha letto che “più alto è meglio per il throughput” e l'ha preso alla lettera. Il consumer mette in buffer 10.000 messaggi, gli acknowledgment restano indietro, la memoria sale e sotto carico l'intero sistema diventa imprevedibile.

“Se avete un prefetch count a zero, significa che state usando l'illimitato. Può anche andare bene, ma siccome avete un throughput molto elevato, quello che consiglio è di mettere semplicemente qualcosa come 100, 200 o giù di lì.”

— Felipe Gutierrez, Senior Engineer, AceMQ (da un intervento di AceMQ per diagnosticare errori di acknowledgment dei consumer in un deployment RabbitMQ enterprise ad alto volume)

È la nostra raccomandazione standard di partenza per i workload ad alto throughput, e si basa su una precisa ragione ingegneristica. Un prefetch nell'intervallo 100–200 dà al broker una profondità di pipeline sufficiente a mantenere il consumer saturo (il consumer non resta mai in attesa del messaggio successivo) senza inondarne la memoria con migliaia di messaggi in transito non ancora elaborati. È il punto di equilibrio per la maggior parte dei workload real-time: partiamo da lì e regoliamo verso l'alto o verso il basso in base a ciò che dicono effettivamente le metriche.

Le risposte sbagliate, in ordine di frequenza con cui le incontriamo:

Perché il prefetch conta così tanto su larga scala

Controlla l'utilizzo della capacità dei consumer

Nella management UI, RabbitMQ riporta una metrica chiamata “consumer capacity”, che indica per quale percentuale del tempo il consumer sta elaborando attivamente messaggi anziché attendere che ne arrivino altri. Un consumer ben ottimizzato opera al 100% della capacità: lavora sempre. Un consumer con un prefetch troppo basso resta al 40%, 60%, 80% della capacità, perché trascorre un tempo misurabile in attesa del messaggio successivo dalla rete. Quel tempo di inattività è throughput che avete pagato e che non ottenete.

Felipe ha una regola operativa precisa: se la consumer capacity scende sotto il 100%, il consumer non riesce a stare al passo con il flusso di messaggi e lo sviluppatore deve essere avvisato. O il prefetch è sbagliato, o il consumer elabora troppo lentamente, o servono più istanze di consumer. In ognuno di questi casi, la prima cosa da controllare è il prefetch.

Governa il comportamento del flow control

RabbitMQ dispone di un meccanismo di flow control che rallenta i publisher quando i consumer non riescono a stare al passo. È una valvola di sicurezza, che impedisce al broker di accumulare un backlog illimitato, ma è anche il segnale che qualcosa a monte non è allineato. Quando il prefetch è regolato correttamente, i consumer svuotano la coda alla massima velocità e il flow control interviene di rado. Quando il prefetch è troppo basso, sotto carico la coda si riempie, il broker entra in flow control, i publisher vengono bloccati e le caratteristiche di latenza dell'intero sistema cambiano.

Ad alto throughput, la distanza tra “va tutto bene” e “i producer vengono bloccati” può essere un unico valore di prefetch scelto male.

Interagisce con il comportamento Raft delle code quorum

Con le code quorum (quorum queues), che nel 2026 sono la scelta della maggior parte dei deployment RabbitMQ enterprise, le interazioni del prefetch diventano ancora più rilevanti. Se non avete ancora completato la migrazione alle code quorum, è il momento di farlo. Le code quorum usano il consenso Raft, il che significa che ogni acknowledgment è una scrittura nel log Raft su una maggioranza di nodi. Un prefetch di 1 su una coda quorum impone un round-trip Raft per ogni singolo messaggio, il che distrugge il throughput. Un prefetch di 100 o 200 consente al broker di raggruppare i commit degli acknowledgment nel log Raft, con un'efficienza nettamente superiore.

Abbiamo visto workload raddoppiare o triplicare il throughput sostenuto dopo un intervento di tuning del prefetch sulle code quorum. I conti sono semplici: meno commit Raft per messaggio significa più messaggi al secondo.

Prefetch globale e individuale: una nota storica che conta ancora

In RabbitMQ 3.x esistevano due modalità di prefetch distinte che le librerie client potevano impostare: globale e individuale. Il prefetch globale si applicava a tutti i consumer di un canale: impostando un prefetch globale di 1.000 con 5 consumer su quel canale, ogni consumer otteneva di fatto 200. Il prefetch individuale si applicava per consumer, quindi un prefetch di 1.000 significava che ogni consumer poteva avere 1.000 messaggi in transito.

In RabbitMQ 4.x la semantica del prefetch è stata chiarita e semplificata, ma il compromesso di fondo resta. Se la vostra architettura avvia più consumer su un singolo canale, dovete capire se la libreria client imposta il prefetch per consumer o per canale, perché il numero effettivo di messaggi in transito è radicalmente diverso.

La raccomandazione pratica: nei sistemi di produzione ad alto throughput, preferite la semantica del prefetch per consumer e un consumer per canale. Questo vi dà un comportamento di memoria e throughput prevedibile per ogni consumer, che scala linearmente quando aggiungete istanze. Inoltre semplifica molto il debug dei problemi di capacità, perché il perimetro prestazionale di ogni consumer è indipendente.

Come regolare davvero il prefetch per il vostro workload

Non esiste un valore di prefetch universalmente corretto. Esiste però un metodo che vi porterà al valore giusto per il vostro workload più rapidamente che andando a tentativi.

Passo 1: partire da 100

Per qualsiasi workload RabbitMQ ad alto throughput che non avete ancora misurato, partite con un prefetch di 100. Non è quasi mai un errore disastroso. È abbastanza alto da creare una pipeline sul percorso dal broker al consumer, abbastanza basso da limitare la pressione sulla memoria del consumer, e vi fornisce una baseline misurabile da cui partire con il tuning.

Passo 2: misurare la consumer capacity con un carico rappresentativo

  • Se la consumer capacity è sotto il 100%, il prefetch potrebbe essere troppo basso: il consumer è in attesa di messaggi.
  • Se la memoria del consumer sale e gli acknowledgment restano indietro, il prefetch potrebbe essere troppo alto: il consumer mette in buffer più di quanto riesca a elaborare.
  • Se la capacità è al 100% e la memoria è stabile, il prefetch è corretto. Lasciatelo così.

Fate passare un carico rappresentativo attraverso la coda e osservate la metrica consumer capacity nella management UI di RabbitMQ. Tenete d'occhio anche l'uso di memoria del consumer. Per la visibilità a livello di cluster, consultate la nostra guida al monitoraggio di RabbitMQ su Kubernetes. Dovete verificare tre condizioni:

Passo 3: regolare con incrementi significativi

Se dovete aumentarlo, provate 200, poi 500. Non passate da 100 a 10.000: la relazione tra prefetch e throughput non è lineare. Ogni raddoppio dovrebbe mostrare all'inizio un miglioramento misurabile del throughput, poi rendimenti decrescenti e infine rendimenti negativi, quando il consumer comincia a faticare a gestire il proprio buffer.

Passo 4: tenere conto della dimensione dei messaggi

Un prefetch di 200 con messaggi da 1KB corrisponde a 200KB di memoria in transito per consumer. Un prefetch di 200 con messaggi da 1MB corrisponde a 200MB di memoria in transito per consumer. Se i vostri messaggi sono grandi, e nelle pipeline real-time spesso lo sono, il prefetch deve essere più basso rispetto al caso dei messaggi piccoli. Calcolate la memoria massima in transito come prefetch_count × p99_message_size e dimensionate di conseguenza la memoria dei consumer. Non dimenticate questo calcolo negli ambienti con messaggi di dimensioni eterogenee.

Passo 5: testare ai limiti di guasto

Il valore di prefetch giusto è quello che offre buone prestazioni sia con il carico a regime SIA durante gli scenari di ripristino. Simulate la caduta di un consumer mentre la coda ha dei messaggi accumulati. Quando il consumer sostitutivo si avvia, smaltisce il backlog in modo pulito alla velocità prevista? Oppure la sua configurazione di prefetch lo lascia a secco o lo sommerge? Valori di prefetch che sembrano corretti a regime possono comportarsi male durante un failover, che è esattamente il momento in cui devono comportarsi bene.

La trappola della dimensione dei messaggi: perché il prefetch da solo non basta

Una delle trappole operative più comuni che vediamo nei deployment RabbitMQ ad alto throughput è considerare il prefetch l'unica leva quando il vero problema è la dimensione dei messaggi. RabbitMQ è un message broker, non un database, e non è nemmeno un sistema di trasferimento file.

Abbiamo visto deployment RabbitMQ di produzione in cui l'operatore lamentava un throughput “misteriosamente” limitato a una frazione del valore atteso, per poi scoprire, dopo un'analisi, che l'applicazione inviava come payload dei messaggi PDF da diversi megabyte, clip video o snapshot serializzati di database. Nessun tuning del prefetch risolve una situazione del genere. Il broker fa ciò che gli è stato chiesto: solo che gli è stato chiesto di fare qualcosa che non dovrebbe fare.

La regola architetturale è: mantenete piccoli i messaggi RabbitMQ. Una revisione dell'architettura RabbitMQ può aiutare a individuare dove la dimensione dei payload penalizza il throughput. Se dovete far transitare un payload di grandi dimensioni nel sistema, scrivetelo su un object storage e inviate un riferimento tramite RabbitMQ. Messaggi da 4KB attraversano un cluster ordini di grandezza più velocemente di messaggi da 4MB, anche con impostazioni di prefetch identiche, perché:

  • I messaggi più piccoli consumano meno banda di rete per messaggio.
  • I messaggi più piccoli consumano meno memoria sia nei buffer del broker sia in quelli del consumer.
  • I messaggi più piccoli vengono resi persistenti su disco più rapidamente nelle code quorum.
  • I messaggi più piccoli vengono replicati più rapidamente sui follower Raft.

In senso stretto, non è un problema di prefetch. Ma qualsiasi discussione sul tuning del prefetch per i sistemi real-time ad alto throughput deve includere la verifica delle dimensioni, perché ottimizzare il prefetch su una pipeline di messaggi da 4MB significa intervenire sul livello sbagliato.

Quando rivedere il prefetch

Il prefetch non è un parametro da impostare e dimenticare. Rivedete la configurazione del prefetch quando:

  • Cambiano i requisiti di throughput. Una crescita di 10 volte del volume di messaggi significa spesso che un prefetch adeguato alla vecchia scala è sbagliato per quella nuova.
  • Cambia la distribuzione delle dimensioni dei messaggi. Nuove funzionalità applicative che inviano messaggi più grandi cambiano i calcoli sulla memoria.
  • Migrate alle code quorum. L'overhead dei commit Raft cambia il valore di prefetch ottimale, di solito verso l'alto.
  • Cambiate l'architettura dei consumer. Passare da N consumer su un solo canale a N consumer ciascuno sul proprio canale cambia completamente i calcoli sul prefetch.
  • Vedete una consumer capacity sotto il 100% sotto carico. È il segnale più chiaro in assoluto che qualcosa nella catena prefetch + consumer + broker non è allineato.
  • Vedete il flow control attivarsi con carichi che non dovrebbero provocarlo. Il flow control è il broker che vi dice che i consumer non riescono a stare al passo. Il prefetch è uno dei primi punti da controllare.

In pratica

Il prefetch è il parametro di tuning lato consumer con la leva più alta in RabbitMQ. Sbagliarlo ad alto throughput si traduce in limiti di capacità misteriosi, comportamenti imprevedibili della memoria, eventi di flow control con carichi che non dovrebbero causarli e ticket di supporto che dicono “RabbitMQ sembra lento” senza indicare una causa precisa.

Impostarlo correttamente non si nota affatto, ed è esattamente ciò che si vuole: consumer al 100% della capacità, memoria stabile, latenza contenuta e un throughput che scala in modo prevedibile man mano che si aggiungono istanze di consumer.

Se oggi state avviando un nuovo workload RabbitMQ real-time e vi serve un punto di partenza senza avere il tempo per un tuning completo: prefetch = 100, per consumer, un consumer per canale. Misurate la consumer capacity, regolate da lì e verificate le dimensioni dei messaggi prima di toccare qualsiasi altro parametro. Questa sola raccomandazione, applicata con coerenza, previene buona parte dei problemi di prestazioni per cui veniamo chiamati.

Per i workload che spingono al limite (centinaia di migliaia di messaggi al secondo, SLA sotto i 10ms, durabilità di livello finanziario) il tuning diventa più sfumato, e le interazioni con code quorum, Raft e architettura dei consumer richiedono più attenzione. Ma il punto di partenza è lo stesso, e lo è anche il metodo: partire da 100, misurare, regolare e mantenere piccoli i messaggi.

State ottimizzando un cluster RabbitMQ ad alto throughput e avete raggiunto un limite?

Il team di ingegneria di AceMQ ha ottimizzato cluster RabbitMQ che operano agli estremi: piattaforme di trading, sistemi di pagamento, pipeline sanitarie globali e ambienti di analytics real-time che gestiscono centinaia di migliaia di messaggi al secondo. Il prefetch è solo un tassello del puzzle. Se il vostro cluster è limitato al di sotto di dove dovrebbe essere, possiamo individuare il collo di bottiglia (broker, consumer, tipo di coda, rete, disco) e riportarvi a uno scaling lineare.

Se state costruendo un nuovo workload ad alto throughput e volete impostare correttamente architettura e tuning fin dall'inizio, oppure avete un cluster esistente che non rende come dovrebbe, parlate con il nostro team di un assessment delle prestazioni. Ci occupiamo di consulenza RabbitMQ, supporto commerciale RabbitMQ e troubleshooting approfondito di RabbitMQ per clienti enterprise in tutto il mondo: è l'unica cosa che facciamo.

Prefetch count: le risposte in breve

Il prefetch count è il numero massimo di messaggi non confermati che RabbitMQ invia a un consumer (o a un canale) prima di fermarsi e attendere gli ack. Tutto il resto deriva da questo unico limite.

Da dove partire. Per la maggior parte dei workload, impostate il prefetch tra 10 e 30 e misurate. Usate 1 quando vi serve un ordinamento rigoroso tra consumer o quando ogni messaggio richiede secondi di elaborazione, perché qualsiasi valore più alto parcheggia lavoro su un consumer che non riesce a occuparsene. Salite di più, nell'intervallo 100–300, solo quando i consumer sono veloci e idempotenti e un test di carico ha confermato che l'host del consumer ha memoria sufficiente. Una volta saturato il consumer, più grande non significa più veloce: sposta soltanto il backlog dal broker al client.

Perché 0 crea più problemi di tutti. Un prefetch di 0 significa illimitato. Il broker invia ogni messaggio pronto al primo consumer con un canale aperto, quindi un consumer accaparra la coda mentre gli altri restano inattivi. La stessa impostazione è alla base della maggior parte dei problemi di memoria lato consumer per cui veniamo chiamati: una coda si svuota su un singolo processo che non riesce a confermare abbastanza velocemente, e il processo va in swap o viene terminato. Se una coda sembra vuota ma il throughput è scarso e un consumer è bloccato al 100% di CPU, controllate per prima cosa se il prefetch è 0.

Il prefetch esiste solo per i consumer con ack manuale. Con l'auto-ack, il broker considera un messaggio confermato nel momento in cui lo invia, quindi non c'è mai nulla in sospeso da conteggiare rispetto al limite. Impostare un prefetch su un consumer con auto-ack non ha alcun effetto.

Code quorum e stream non sono code classiche. Le code quorum rispettano il prefetch, ma tengono anche traccia di un contatore di consegne per messaggio e applicano un delivery-limit (20 per default nella 4.x). Un consumer con un prefetch elevato che va in crash restituisce ogni messaggio non confermato con il contatore incrementato, quindi pochi riavvii possono mandare in dead letter messaggi che non erano affatto problematici. Gli stream sono ancora diversi. Con il protocollo stream, il controllo di flusso è basato sui crediti, non sul prefetch. Su AMQP 0-9-1, un consumer di stream deve impostare un prefetch diverso da zero e usare ack manuali, e l'ack non cancella nulla: restituisce credito affinché il broker invii altri messaggi. Consultate code classiche e code quorum a confronto per un confronto più completo.

Tre motivi per cui il prefetch "non funziona" in un test di carico. Primo, il consumer usa l'auto-ack e l'impostazione viene ignorata. Secondo, il flag global: in RabbitMQ, global=false limita ogni consumer e global=true limita l'intero canale, e alcune librerie client usano un default diverso o interpretano quel flag in modo diverso. Terzo, il framework client applica un proprio default (spesso 1, a volte 250) dopo l'esecuzione del vostro codice, o su un canale diverso da quello che avete configurato. Verificate il valore effettivo con rabbitmqctl list_consumers invece di fidarvi del codice.

Il prefetch è il quinto di dieci pattern della guida all'affidabilità di RabbitMQ e il settimo passaggio della guida al clustering e al dimensionamento, che copre la metà lato cluster della stessa questione di throughput.

Domande frequenti

Qual è un buon valore di prefetch count per RabbitMQ?

Partite da 10–30 per i consumer tipici e regolate da lì con un test di carico. Usate 1 per i task di lunga durata o quando conta l'ordinamento tra consumer. Riservate 100–300 ai consumer veloci e idempotenti, dopo aver verificato che l'host del client abbia memoria sufficiente per altrettanti messaggi in transito. In produzione non lasciatelo mai a 0: significa illimitato, ed è la causa più comune in assoluto di un consumer che accaparra un'intera coda mentre gli altri restano inattivi. Il numero giusto è il valore più piccolo che mantiene occupati i consumer.

Perché il prefetch count di RabbitMQ non funziona?

Tre cause coprono quasi tutti i casi che abbiamo analizzato. Il consumer usa l'auto-ack, quindi il prefetch viene del tutto ignorato. Il flag global è impostato al contrario rispetto a quanto vi aspettate, quindi il limite si applica per canale anziché per consumer o viceversa. Oppure il framework client imposta un proprio default dopo l'esecuzione del vostro codice, o su un canale diverso da quello che avete configurato. Verificate il valore effettivo con rabbitmqctl list_consumers. Se il comportamento resta anomalo, l'articolo sui 10 problemi più comuni di RabbitMQ e come risolverli copre le modalità di guasto correlate.

Il prefetch count vale anche per le code quorum e gli stream?

Le code quorum (quorum queues) rispettano il prefetch esattamente come le code classiche, con un'aggiunta: ogni riconsegna incrementa un contatore di consegne per messaggio e, superato il delivery-limit, il messaggio viene inviato alla dead letter o scartato. Un consumer che va in crash con un prefetch elevato spinge molti messaggi verso quel limite contemporaneamente, quindi sulle code quorum mantenete un prefetch moderato. Gli stream su AMQP 0-9-1 richiedono un prefetch diverso da zero e ack manuali, ma l'ack restituisce solo credito, non rimuove il messaggio. Con il protocollo stream nativo, il controllo di flusso è basato sui crediti e il prefetch non è proprio il modello di riferimento.

Il prefetch va impostato per canale o per consumer?

Per consumer, in quasi tutti i casi. In RabbitMQ, global=false (il default nella maggior parte dei client) applica il limite a ciascun consumer in modo indipendente, che è ciò che ci si aspetta e che rende prevedibile il tuning. global=true applica un unico limite condiviso a tutti i consumer del canale, utile solo quando più consumer su un canale devono condividere un budget fisso di messaggi in transito. Se li impostate entrambi, il broker li applica entrambi. Quando prendiamo in carico un ambiente RabbitMQ dalla 3.8 alla 4.x con il supporto gestito, il controllo di questo flag è una delle prime cose che facciamo, perché spiega un numero sorprendente di lamentele sul throughput.

Scott Sternloff

Autore

Scott SternloffEnterprise Architect senior

Enterprise Architect senior di AceMQ. Firma qui gli articoli tecnici: architettura, clustering e migrazioni di RabbitMQ, Kafka e Redis.

Consulenza gratuita

Fate esaminare a un esperto il vostro cluster RabbitMQ

Che stiate risolvendo un incidente in produzione, pianificando una migrazione o cercando un secondo parere sulla vostra architettura, il nostro team è pronto. Nessun discorso commerciale, solo risposte.

Scriveteci