Guia · RabbitMQ

Guia de streams do RabbitMQ

Os streams são o terceiro tipo de fila do RabbitMQ e o que mais vezes é escolhido pelo motivo errado. Este guia trata deles na ordem em que você os encontra em produção: o que são, quando se encaixam, como funcionam a retenção e os offsets, como operá-los e o que eles não garantem. Todo comportamento descrito vem da documentação do RabbitMQ 4.3, conferida em 20 de setembro de 2026.

Tyler Eastridge

Por Tyler Eastridge, Head de operações

LinkedIn · Atualizado em · 7 min de leitura · 9 seções

Nesta página

Streams em um parágrafo

Streams em um parágrafo

Um stream é um log replicado, somente de inserção (append-only), que os consumidores leem sem remover as mensagens. Use-o para fan-out, replay, alto throughput e backlogs grandes; use uma quorum queue quando precisar de dead-lettering, TTL, prioridades ou durabilidade no nível do fsync. Declare-o com x-queue-type definido como stream, configure max-age ou max-length-bytes desde o primeiro dia, dê a cada consumidor um prefetch e um offset, rode-o em uma quantidade ímpar de nós, gerencie as réplicas você mesmo e lembre-se de que uma confirmação significa replicado, e não gravado em disco.

O que é um stream do RabbitMQ

Um stream é um log persistente, replicado e somente de inserção que fica no RabbitMQ ao lado das filas clássicas e das filas de quórum (quorum queues). A diferença está em como as mensagens saem dele: elas não saem. Consumir de uma fila remove a mensagem; consumir de um stream só move a posição daquele consumidor, então qualquer quantidade de consumidores pode ler as mesmas mensagens, quantas vezes quiser, até que a retenção as expire. A documentação do RabbitMQ chama isso de semântica de consumo não destrutiva. Os streams são sempre duráveis e sempre replicados; não existe variante transitória.

Quando um stream é o tipo certo, e quando não é

Os streams foram criados para quatro casos que os tipos de fila atendem mal: fan-out grande (muitos consumidores lendo as mesmas mensagens sem uma fila para cada um), replay (conectar-se em qualquer ponto do log e ler a partir dali), throughput (o objetivo do design era competir com sistemas baseados em log) e backlogs grandes (as filas são otimizadas para convergir para o vazio; os streams armazenam milhões de mensagens com um uso mínimo de memória).

Eles são o tipo errado quando você precisa de recursos de fila. Os streams não suportam dead letter exchanges, TTL de mensagens, limites de tamanho de fila, prioridade de mensagens ou de consumidores, exclusividade nem declaração não durável, e a documentação deixa explícito que muitos desses recursos nunca serão suportados por causa do modelo de leitura não destrutiva. Se a carga de trabalho é distribuição de trabalho com retries e dead-lettering, isso é uma quorum queue.

Stream e fila do RabbitMQ, lado a lado:

Fila (de quórum ou clássica)Stream
Como as mensagens são lidasDestrutiva: uma mensagem com ack é removidaNão destrutiva: os consumidores leem a partir de um offset e a mensagem permanece
Muitos consumidores, os mesmos dadosUma fila por consumidor, cada uma com a sua cópiaUm único stream, qualquer quantidade de consumidores
ReplayNãoSim, a partir de qualquer offset que ainda esteja dentro da retenção
Quanto tempo as mensagens ficamAté serem consumidas, ou até um TTL ou um limite de tamanho removê-lasAté que max-age ou max-length-bytes as expirem
Dead-lettering, TTL de mensagens, prioridadesSuportados nas quorum queuesNão suportados
Backlogs grandesProjetada para convergir para o vazioProjetado para guardar milhões de mensagens

Declarando um stream e configurando a retenção

Declare uma fila com o argumento x-queue-type definido como stream. O tipo precisa ser informado pelo cliente na declaração; ele não pode ser definido nem alterado por policy. Um stream continua sendo uma fila AMQP 0.9.1, então faz binding com qualquer exchange como uma fila.

Configure a retenção desde o primeiro dia, porque um log somente de inserção cresce até encher o disco. São duas configurações, que podem ser usadas juntas e alteradas por policy: max-age (unidades Y, M, D, h, m, s, então 7D é uma semana) e max-length-bytes. A retenção é avaliada por arquivo de segmento, e o tamanho padrão de segmento é 500 MB, então um stream sempre mantém pelo menos um segmento e fica acima do limite configurado em até um segmento. Dimensione o disco para o limite mais um segmento por stream, e não só para o limite.

Consumo: offsets, prefetch e acknowledgements

O consumidor escolhe onde começar com o argumento x-stream-offset: first, last (o último chunk escrito), next (o padrão: só mensagens novas), um offset numérico, um timestamp ou um intervalo como 1h. Os timestamps são resolvidos para os limites dos chunks, então um consumidor pode receber mensagens publicadas um pouco antes do horário que pediu.

Duas regras pegam as equipes que vêm das filas. Os consumidores precisam definir um prefetch de QoS, e os acknowledgements são obrigatórios: em um stream, o ack funciona como um crédito que avança o offset do consumidor. E o QoS global não é suportado; consumir de um stream em um canal com prefetch global retorna um erro de canal. Use prefetch por consumidor.

Metas de resposta a partir de 15 minutos, conforme o plano. Engenheiros sêniores designados.

Fale conosco

AMQP 0.9.1 ou o protocolo de streams

Qualquer cliente AMQP 0.9.1 que consiga passar argumentos de fila e de consumidor pode usar um stream. A equipe do RabbitMQ ainda recomenda o protocolo binário dedicado de streams e os seus clientes, por dois motivos: ele oferece o melhor throughput, e alguns recursos só existem nele. O rastreamento de offsets no broker é um deles: está disponível apenas pelo plugin de streams, e os offsets são armazenados no próprio stream como dados que não são mensagens. A deduplicação no publisher é outro: um producer nomeado com um publishing ID estritamente crescente permite ao broker filtrar as mensagens reenviadas após um crash, desde que só uma instância do producer use esse nome por vez.

Um efeito colateral que você precisa conhecer: as mensagens são armazenadas como dados AMQP 1.0, então headers AMQP 0.9.1 com valores complexos, como arrays ou tables, não são convertidos.

Super streams e single active consumer

Um super stream é um stream lógico particionado em vários streams comuns, o que distribui o armazenamento e o tráfego pelos nós do cluster. As bibliotecas cliente o apresentam como um único stream. Combinado com o single active consumer, em que só uma instância de um grupo nomeado recebe mensagens e outra assume se ela parar, você obtém processamento ordenado por partição com failover. Os dois chegaram no RabbitMQ 3.11. A CLI cria a topologia em uma linha: rabbitmq-streams add_super_stream invoices --partitions 3.

A própria documentação recomenda moderação: os super streams adicionam complexidade e só devem ser usados quando um único stream tiver chegado aos seus limites.

Operando streams: réplicas, quórum e memória

Os streams são sistemas de quórum, então use clusters com quantidade ímpar de nós: três nós toleram uma falha, cinco toleram duas e um cluster de dois nós não tolera nenhuma. A participação nas réplicas é gerenciada pelo operador. Um nó adicionado ao cluster não hospeda nenhuma réplica de stream até você rodar rabbitmq-streams add_replica, e um nó que está sendo desativado precisa ser removido com delete_replica de cada stream que ele hospeda. Verifique a replicação com rabbitmq-streams stream_status. Ao substituir um nó, adicione o novo, espere ele ficar sincronizado e só então remova o antigo; não é possível adicionar uma réplica enquanto outra estiver dessincronizada.

Os streams usam pouca RAM no broker, mas dependem muito do page cache do kernel. Em contêineres, esse page cache conta para o limite de memória, e é assim que uma carga de streams saudável faz um pod ser encerrado por OOM. Os streams também não reagem aos memory alarms. Use os discos mais rápidos disponíveis; o throughput cai à medida que o tamanho das mensagens e a quantidade de réplicas aumentam.

Segurança dos dados: o que um publisher confirm significa em um stream

Uma confirmação em um stream significa que a mensagem foi replicada para um quórum de réplicas. Ela não significa que a mensagem foi gravada em disco: os streams escrevem no disco, mas não fazem fsync, deixando isso para o sistema operacional. Um desligamento não controlado pode, portanto, perder dados recentes naquele nó, que normalmente são replicados de novo a partir dos outros. A orientação da documentação é direta: se você precisa de garantias mais fortes, use quorum queues, que só confirmam depois que um quórum escreveu e fez o flush. Mensagens publicadas sem confirmações não têm garantia nenhuma.

Onde você não consegue rodá-los

Verifique a plataforma antes do design. O Amazon MQ for RabbitMQ não suporta streams, e a documentação dele avisa que criar um stream vai resultar em perda de dados. Os streams exigem RabbitMQ autogerenciado, um provedor especializado ou brokers na sua própria conta operados para você.

Perguntas frequentes

Qual é a diferença entre um stream e uma fila no RabbitMQ?

Uma fila remove a mensagem assim que um consumidor faz o ack, então cada mensagem é processada uma vez e a fila esvazia. Um stream guarda as mensagens até que a retenção as expire, e os consumidores leem a partir de um offset, então muitos consumidores podem ler as mesmas mensagens e fazer replay delas. As filas têm dead-lettering, TTL e prioridades; os streams não.

O que é um stream do RabbitMQ?

Um log persistente, replicado e somente de inserção dentro do RabbitMQ. Os consumidores o leem sem remover as mensagens, então muitos consumidores podem ler os mesmos dados e relê-los a partir de qualquer offset até que a retenção os expire. Para declarar um, defina x-queue-type como stream.

Quando devo usar um stream em vez de uma quorum queue?

Use um stream para fan-out grande, replay, throughput muito alto ou backlogs grandes. Use uma quorum queue para distribuição de trabalho que precisa de dead-lettering, TTL, prioridades ou da durabilidade mais forte, porque as quorum queues só confirmam depois que um quórum gravou em disco, e os streams não fazem fsync.

Como evitar que um stream do RabbitMQ encha o disco?

Configure a retenção com max-age, max-length-bytes ou os dois, por argumento da fila ou por policy. A retenção é aplicada por segmento e o segmento padrão tem 500 MB, então reserve pelo menos um segmento extra de folga por stream.

Os streams do RabbitMQ suportam dead letter exchanges ou TTL?

Não. Os streams não suportam dead letter exchanges, TTL de mensagens, limites de tamanho de fila, prioridades nem declaração exclusiva ou não durável. As configurações de retenção substituem o TTL e os limites de tamanho.

O Amazon MQ suporta streams do RabbitMQ?

Não. O guia do desenvolvedor do Amazon MQ afirma que os streams não são suportados e que criar um vai resultar em perda de dados.

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