Guia · RabbitMQ

Guia de RabbitMQ Streams

Os streams são o terceiro tipo de fila do RabbitMQ e o que mais vezes é escolhido pelo motivo errado. Este guia trata-os pela ordem em que surgem em produção: o que são, quando se adequam, como funcionam a retenção e os offsets, como se operam e o que não garantem. Todo o comportamento descrito foi retirado da documentação do RabbitMQ 4.3, verificada a 20 de setembro de 2026.

Tyler Eastridge

Por Tyler Eastridge, Diretor de operações

LinkedIn · Atualizado a · 8 min de leitura · 9 secções

Nesta página

Os streams num parágrafo

Os streams num parágrafo

Um stream é um log replicado e só de acrescento (append-only) que os consumidores leem sem remover as mensagens. Use-o para fan-out, replay, débito elevado e grandes backlogs; use uma fila de quórum quando precisar de dead-lettering, TTL, prioridades ou durabilidade ao nível do fsync. Declare-o com x-queue-type definido como stream, defina max-age ou max-length-bytes desde o primeiro dia, atribua a cada consumidor um prefetch e um offset, execute-o num número ímpar de nós, faça a gestão das réplicas por conta própria e lembre-se de que um confirm significa replicado, e não gravado em disco.

O que é um stream do RabbitMQ

Um stream é um log persistente, replicado e só de acrescento que existe no RabbitMQ ao lado das filas clássicas e de quórum. A diferença está na forma como as mensagens saem dele: não saem. Consumir de uma fila remove a mensagem; consumir de um stream apenas avança a posição desse consumidor, pelo que qualquer número de consumidores pode ler as mesmas mensagens, tantas vezes quantas quiser, até que a retenção as expire. A documentação do RabbitMQ chama a isto semântica de consumo não destrutivo. Os streams são sempre duráveis e sempre replicados; não existe uma 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 tratam mal: fan-out em grande escala (muitos consumidores a ler as mesmas mensagens sem uma fila para cada um), replay (ligar-se em qualquer ponto do log e ler a partir daí), débito (o objetivo de desenho era competir com sistemas baseados em logs) e grandes backlogs (as filas estão otimizadas para tender a ficar vazias; os streams armazenam milhões de mensagens com um consumo de memória mínimo).

São o tipo errado quando precisa de funcionalidades de fila. Os streams não suportam dead letter exchanges, TTL de mensagens, limites de comprimento da fila, prioridade de mensagens ou de consumidores, exclusividade nem declaração não durável, e a documentação é explícita ao afirmar que muitas destas funcionalidades nunca serão suportadas devido ao modelo de leitura não destrutiva. Se a carga de trabalho for distribuição de trabalho com novas tentativas e dead-lettering, o tipo certo é uma fila de quórum.

Stream e fila do RabbitMQ, lado a lado:

Fila (de quórum ou clássica)Stream
Como são lidas as mensagensDestrutiva: uma mensagem confirmada é 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 stream, qualquer número de consumidores
ReplayNãoSim, a partir de qualquer offset ainda dentro da retenção
Quanto tempo ficam as mensagensAté serem consumidas, ou até um TTL ou um limite de comprimento as removerAté max-age ou max-length-bytes as expirar
Dead-lettering, TTL de mensagens, prioridadesSuportados nas filas de quórumNão suportados
Grandes backlogsConcebida para tender a ficar vaziaConcebido para guardar milhões de mensagens

Declarar um stream e definir a retenção

Declare uma fila com o argumento x-queue-type definido como stream. O tipo tem de ser indicado pelo cliente na declaração; não pode ser definido nem alterado por policy. Um stream continua a ser uma fila AMQP 0.9.1, pelo que se liga a qualquer exchange como uma fila normal.

Defina a retenção desde o primeiro dia, porque um log só de acrescento cresce até o disco encher. Há duas definições, que podem ser usadas em conjunto e alteradas por policy: max-age (unidades Y, M, D, h, m, s, pelo que 7D corresponde a uma semana) e max-length-bytes. A retenção é avaliada por ficheiro de segmento e o tamanho de segmento por omissão é de 500 MB, pelo que um stream mantém sempre pelo menos um segmento e pode ficar até um segmento acima do limite configurado. Dimensione o disco para o limite mais um segmento por stream, e não apenas para o limite.

Consumir: offsets, prefetch e acknowledgements

Um consumidor escolhe onde começar com o argumento x-stream-offset: first, last (o último chunk escrito), next (o valor por omissão: apenas mensagens novas), um offset numérico, um timestamp ou um intervalo como 1h. Os timestamps são resolvidos para os limites dos chunks, pelo que um consumidor pode receber mensagens publicadas ligeiramente antes do instante que pediu.

Há duas regras que apanham desprevenidas as equipas que vêm das filas. Os consumidores têm de definir um prefetch de QoS e os acknowledgements são obrigatórios: num stream, o ack funciona como um crédito que faz avançar o offset do consumidor. E o QoS global não é suportado; consumir de um stream num canal com prefetch global devolve um erro de canal. Use prefetch por consumidor.

Objetivos de resposta a partir de 15 minutos, consoante o plano. Engenheiros seniores designados.

Contacte-nos

AMQP 0.9.1 ou o protocolo de streams

Qualquer cliente AMQP 0.9.1 capaz de passar argumentos de fila e de consumidor pode usar um stream. A equipa do RabbitMQ continua a recomendar o protocolo binário dedicado aos streams e os respetivos clientes, por dois motivos: oferece o melhor débito e há funcionalidades que só existem aí. O registo de offsets do lado do broker é uma delas: só está disponível através do plugin de streams, e os offsets são guardados no próprio stream como dados que não são mensagens. A deduplicação no publisher é outra: um producer com nome e um publishing ID estritamente crescente permite ao broker filtrar mensagens reenviadas após uma falha, desde que apenas uma instância de producer use esse nome de cada vez.

Um efeito secundário a conhecer: as mensagens são armazenadas como dados AMQP 1.0, pelo que os headers AMQP 0.9.1 com valores complexos, como arrays ou tabelas, não são convertidos.

Super streams e single active consumer

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

O próprio conselho da documentação é a contenção: os super streams acrescentam complexidade e só devem ser usados quando um único stream tiver atingido os seus limites.

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

Os streams são sistemas de quórum, por isso use clusters com um número í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 composição das réplicas é gerida pelo operador. Um nó acrescentado ao cluster não aloja réplicas de streams até executar rabbitmq-streams add_replica, e um nó a desativar tem de ser removido com delete_replica de todos os streams que aloja. Verifique a replicação com rabbitmq-streams stream_status. Ao substituir um nó, acrescente o novo, espere que fique sincronizado e só depois remova o antigo; não é possível acrescentar uma réplica enquanto outra estiver dessincronizada.

Os streams usam pouca RAM no broker, mas dependem muito da page cache do kernel. Em contentores, essa page cache conta para o limite de memória, e é assim que uma carga de trabalho de streams perfeitamente saudável faz com que um pod seja terminado por OOM. Os streams também não reagem aos alarmes de memória. Use os discos mais rápidos disponíveis; o débito diminui à medida que aumentam o tamanho das mensagens e o número de réplicas.

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

Um confirm num stream significa que a mensagem foi replicada para um quórum de réplicas. Não significa que tenha sido gravada em disco: os streams escrevem em disco, mas não fazem fsync, deixando isso ao sistema operativo. Um encerramento não controlado pode, por isso, perder dados recentes nesse nó, que normalmente são replicados de novo a partir dos outros. A orientação da documentação é direta: se precisa de garantias mais fortes, use filas de quórum, que só confirmam depois de um quórum ter escrito e gravado em disco. As mensagens publicadas sem confirms não têm qualquer garantia.

Onde não é possível usá-los

Verifique a plataforma antes do desenho. O Amazon MQ for RabbitMQ não suporta streams, e a sua documentação avisa que criar um resultará em perda de dados. Os streams exigem RabbitMQ autogerido, um fornecedor de alojamento especializado ou brokers na sua própria conta operados por terceiros.

Perguntas frequentes

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

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

O que é um stream do RabbitMQ?

Um log persistente, replicado e só de acrescento dentro do RabbitMQ. Os consumidores leem-no sem remover mensagens, pelo que muitos consumidores podem ler os mesmos dados e voltar a lê-los a partir de qualquer offset até a retenção os expirar. Declara-se um definindo x-queue-type como stream.

Quando devo usar um stream em vez de uma fila de quórum?

Use um stream para fan-out em grande escala, replay, débito muito elevado ou grandes backlogs. Use uma fila de quórum para distribuição de trabalho que precise de dead-lettering, TTL, prioridades ou da durabilidade mais forte, porque as filas de quórum só confirmam depois de um quórum ter gravado em disco e os streams não fazem fsync.

Como evito que um stream do RabbitMQ encha o disco?

Defina a retenção com max-age, max-length-bytes ou ambos, por argumento da fila ou por policy. A retenção é aplicada por segmento e o segmento por omissão tem 500 MB, por isso preveja pelo menos um segmento adicional de margem 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 comprimento da fila, prioridades nem declaração exclusiva ou não durável. As definições de retenção substituem o TTL e os limites de comprimento.

O Amazon MQ suporta streams do RabbitMQ?

Não. O guia do programador do Amazon MQ indica que os streams não são suportados e que criar um resultará em perda de dados.

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