BlogKafka

Rebalance no Kafka: o que dispara e como acabar com as tempestades

Scott Sternloff

Por Scott Sternloff, Arquiteto corporativo sênior

LinkedIn · Atualizado em · 15 min de leitura

Rebalance no Kafka: o que dispara e como acabar com as tempestades
On this page

Um rebalance no Kafka é o processo de redistribuir partições entre os consumidores de um grupo. Ele é disparado sempre que a composição do grupo muda — um consumidor entra, sai ou é declarado morto — ou quando o número de partições de um tópico assinado muda. Um grupo saudável rebalanceia de vez em quando e por pouco tempo. Um grupo que rebalanceia a cada poucos minutos tem um problema de configuração, e as pausas resultantes costumam ser confundidas com um problema de broker ou de throughput.

O rebalanceamento do Kafka não é uma falha em si. É assim que o Apache Kafka distribui partições para os consumidores e mantém o trabalho equilibrado à medida que um deployment escala. Entender como o rebalanceamento do Kafka funciona importa porque os problemas surgem quando ele dispara com muito mais frequência do que a carga de trabalho justifica.

Vale a pena entender o mecanismo, porque quase toda correção é uma mudança na configuração do consumidor, e não algo feito no cluster.

O que dispara um rebalance no Kafka?

Quatro coisas, e só as duas primeiras são intencionais.

Um novo consumidor entra no grupo. Um aumento de escala ou um pod subindo depois de um deploy. Esperado — quando um novo consumidor entra no grupo, o coordenador distribui as partições entre os consumidores que já estão em execução.

Um consumidor sai de forma limpa. Um desligamento gracioso que envia uma solicitação de saída. Também esperado. Sempre que um consumidor entra ou sai, há uma redistribuição.

Um consumidor é declarado morto. É aqui que mora o problema. O coordenador do grupo inicia um rebalance no momento em que conclui que um consumidor sumiu, o que acontece quando um de dois relógios se esgota:

  • session.timeout.ms (padrão de 45 segundos). O consumidor envia heartbeats em uma thread de background a cada heartbeat.interval.ms (padrão de 3 segundos). Se perder heartbeats demais, o coordenador o expulsa. Isso detecta falhas reais, partições de rede e pausas longas de GC.
  • max.poll.interval.ms (padrão de 5 minutos). O intervalo entre chamadas sucessivas a poll() na thread principal. Os heartbeats continuam fluindo na thread de background, então o consumidor parece vivo — mas, se a aplicação demorar demais para processar um lote, o coordenador o expulsa mesmo assim.

Esse segundo relógio causa a maioria dos rebalances sem explicação em produção. O consumidor não caiu. Ele só está processando devagar, e o Kafka não consegue distinguir um consumidor lento de um travado.

O número de partições muda. Quando novas partições são adicionadas a um tópico do Kafka, há uma nova atribuição. Mudanças de assinatura fazem o mesmo.

Os dois últimos são eventos de rebalance que você preferiria não ter. Disparar um rebalance no Kafka custa o mesmo, seja qual for a causa, e rebalances desnecessários são o que transforma um consumer group funcional em um grupo paralisado.

O que acontece de fato durante um rebalance do Kafka?

Todos os consumidores do grupo param de consumir, precisam entrar no grupo de novo e esperam antes de poder retomar. O líder do grupo — um dos consumidores, e não um broker do Kafka — envia uma requisição ao coordenador do grupo, calcula como as partições serão atribuídas e distribui o resultado. As partições são revogadas primeiro e depois redistribuídas — e qual consumidor fica com quais partições pode mudar a cada rodada.

A propriedade importante é que isso é uma barreira de sincronização: todos os consumidores de um consumer group se movem juntos, e o membro mais lento dita o ritmo. Um consumidor que leva trinta segundos para voltar ao grupo faz o grupo inteiro esperar trinta segundos. Nenhuma mensagem é processada durante o rebalanceamento, então o acúmulo cresce e o lag sobe, mesmo com todos os brokers do cluster Kafka saudáveis.

É por isso que rebalances e lag são confundidos com tanta frequência. Se você está correndo atrás de um lag crescente, e não dos rebalances que o causam, diagnosticar o consumer lag do Kafka cobre o lado dos sintomas.

Rebalanceamento eager versus cooperativo

O protocolo de rebalance do Kafka tem duas gerações, e qual delas você está usando muda enormemente o custo de cada rebalance.

O rebalanceamento eager é o comportamento original, que para tudo (stop-the-world). Cada consumidor revoga todas as partições atribuídas a ele antes de a nova atribuição ser calculada. Mesmo que a redistribuição mova apenas duas partições entre duzentas, tudo para. A pausa cresce com o tamanho do grupo e o tempo de reentrada, e não com o quanto realmente mudou.

O rebalanceamento incremental revoga apenas as partições que de fato estão mudando de dono. Os consumidores continuam processando tudo o que mantêm. O protocolo de rebalanceamento cooperativo roda em duas rodadas mais leves, em vez de uma pesada, de modo que o impacto do rebalance cresce com o tamanho da mudança, e não com o número de membros. Essa abordagem cooperativa incremental é o que a maioria dos ambientes deveria estar usando.

Ela está disponível desde o Kafka 2.4 e nem sempre é o padrão em um cliente Kafka mais antigo. A membership estática chegou um pouco antes, no Kafka 2.3. A mudança é uma linha:

partition.assignment.strategy=org.apache.kafka.clients.consumer.CooperativeStickyAssignor

⚠️ Não basta definir isso e fazer o deploy. Passar de eager para cooperativo exige um upgrade rolling em duas fases — primeiro, faça o deploy com as duas estratégias listadas, para que o grupo consiga chegar a um acordo; depois, remova a eager em uma segunda passada. Mudar de uma só vez em um grupo em execução faz o rebalance falhar.

As releases mais novas vão ainda mais longe. O novo protocolo de rebalance de consumidores move o cálculo da atribuição para o broker e elimina totalmente a barreira de sincronização global, de modo que os consumidores deixam de parar todos juntos. Esse novo protocolo chegou à disponibilidade geral no Apache Kafka 4.0. Se você está em uma release recente, vale a pena avaliá-lo — mas a maioria dos ambientes de produção ainda não chegou lá, e o sticky assignor entrega a maior parte do benefício hoje.

Comparação entre o rebalanceamento eager, que para todos os consumidores, e o rebalanceamento cooperativo incremental, que move apenas as partições afetadas

Estratégias de atribuição de partições

AssignorComportamentoCusto do rebalance
RangeAssignorFaixas contíguas por tópicoEager; pode distribuir de forma desigual entre vários tópicos
RoundRobinAssignorDistribuição uniforme entre todas as partiçõesEager; redistribui tudo
StickyAssignorDistribuição uniforme, preservando a atribuição anterior sempre que possívelEager, mas move menos partições
CooperativeStickyAssignorSticky, e revoga apenas o que muda de donoIncremental — o que você quer

A estabilidade da atribuição (stickiness) importa para além da pausa em si. Quando um consumidor mantém as mesmas partições de tópico durante um rebalance, ele mantém o estado local aquecido — caches, agregações em andamento, state stores do Kafka Streams. Embaralhar sem necessidade joga isso fora, e o custo de recuperação muitas vezes supera o próprio rebalance.

Se você usa Spring Kafka ou outro framework como camada sobre o cliente, isso é definido pela mesma propriedade subjacente — o framework não muda quais estratégias estão disponíveis para você.

Tabela de estratégias de atribuição de partições do Kafka comparando os assignors range, round robin, sticky e cooperative sticky

A tempestade de rebalances no Kafka: por que ela nunca se resolve sozinha

Os problemas de rebalanceamento que trazem as pessoas até nós quase sempre seguem o mesmo roteiro:

  1. O processamento fica mais lento — uma API downstream se degrada ou um lote fica maior.
  2. Um consumidor ultrapassa max.poll.interval.ms e é expulso.
  3. O grupo rebalanceia. Todo mundo para.
  4. O acúmulo cresce durante a pausa.
  5. Na retomada, cada consumidor puxa um lote completo diante de um acúmulo maior e leva mais tempo para processá-lo.
  6. Outro consumidor ultrapassa o intervalo. Volte ao passo 3.

O throughput de processamento despenca enquanto o cluster em si continua saudável.

Ela nunca se resolve sozinha, porque cada novo rebalance do Kafka torna o próximo mais provável — e é exatamente por isso que as equipes começam a investigar o cluster, e não a forma como configuram o consumidor.

Quebrar o ciclo geralmente é uma questão de fazer os lotes terminarem dentro do intervalo:

  • Reduza max.poll.records. A mudança isolada mais eficaz. Menos registros por poll significa menos tempo entre polls. Comece reduzindo pela metade.
  • Aumente max.poll.interval.ms para que ele de fato supere o tempo de processamento no pior caso, e não o tempo típico. Meça o p99; não estime.
  • Tire o trabalho lento da thread de polling. Se o processamento envolve uma chamada de rede de duração imprevisível, o loop de poll é o lugar errado para ela.
  • Não aumente session.timeout.ms para resolver isso. É outro relógio e não vai ajudar — só atrasa a detecção de consumidores realmente mortos.
Diagrama do ciclo de realimentação: processamento lento ultrapassa max.poll.interval.ms, dispara um rebalance, o acúmulo cresce e novos rebalances acontecem

Membership estática

Onde os consumidores reiniciam com frequência — deploys rolling no Kubernetes, o caso mais óbvio —, isso impede que a reinicialização dispare um rebalance.

Atribua a cada consumidor um group.instance.id estável. Em uma reinicialização dentro da janela de timeout, o coordenador reconhece o membro que está voltando e devolve as partições anteriores dele sem redistribuir nada:

group.instance.id=consumer-3
session.timeout.ms=45000

O trade-off é claro: um membro realmente morto só é substituído quando a sessão dele expira, então as partições dele ficam sem consumo durante essa janela. Antes de habilitar, decida se o rebalance é necessário na reinicialização. Defina o timeout para superar com folga o tempo do seu restart rolling, e nada além disso.

Há também uma configuração no broker que vale conhecer para a inicialização. group.initial.rebalance.delay.ms (padrão de 3 segundos) faz o coordenador esperar um pouco antes do primeiro rebalance, para que consumidores que sobem juntos formem um único grupo, em vez de rebalancear repetidamente à medida que cada um chega. É um detalhe que elimina muito ruído em deploys no Kubernetes.

O que monitorar

Acompanhe três coisas, e acompanhe as três juntas:

  • Taxa de rebalances. O próprio sinal. Qualquer coisa acima de ocasional merece investigação — e um consumidor preso em um loop de rebalance aparece aqui primeiro.
  • Duração dos rebalances. Uma duração crescente significa que os consumidores estão demorando para voltar ao grupo — muitas vezes, o mesmo processamento lento que disparou o rebalance.
  • Consumer lag durante os rebalances. Confirma se as pausas estão de fato custando throughput ou se são curtas o bastante para não importar.

Um consumer group que passa por um rebalance do Kafka algumas vezes por dia, em torno dos deploys, está bem. Um que rebalanceia a cada poucos minutos está dizendo que max.poll.interval.ms está sendo ultrapassado, e nenhum ajuste no cluster vai mudar isso.

Está vendo tempestades de rebalance ou pausas inexplicáveis nos consumidores? Elas quase sempre estão na configuração

do consumidor, e não no cluster, e é por isso que as métricas do broker parecem limpas enquanto o throughput

despenca. A AceMQ faz avaliações estruturadas de Kafka que as encontram —

Se uma única pessoa concentra todo esse conhecimento, isso é um risco de equipe, e não de Kafka: quanto custa de verdade dar suporte ao Kafka por conta própria.

Rebalanceamento cooperativo na prática: como verificar, como migrar e o que o Streams e o Connect fazem

Range, round-robin e o sticky assignor original usam todos o protocolo eager. Em qualquer mudança de composição, o coordenador leva o grupo para PreparingRebalance, cada consumidor revoga todas as partições que possui, todos voltam ao grupo e o líder distribui uma atribuição nova. O grupo inteiro para durante esse ciclo.

O Kafka 2.4 introduziu o rebalanceamento cooperativo para consumidores. No protocolo cooperativo incremental, um rebalance roda em duas fases. Na primeira, o líder calcula a nova atribuição e cada consumidor revoga apenas as partições que estão saindo dele, enquanto continua fazendo poll e commit de todo o resto. Um segundo rebalance vem logo em seguida, e nele as partições liberadas vão para os novos donos. O único assignor do lado do cliente que usa esse protocolo é o CooperativeStickyAssignor.

A maioria dos grupos para os quais somos chamados está rodando eager sem saber. Primeiro, a configuração do consumidor: partition.assignment.strategy é uma lista, e nos clientes recentes a lista padrão contém tanto range quanto cooperative-sticky. O coordenador seleciona uma estratégia que todos os membros suportam, então o padrão acaba caindo em range. Segundo, descreva o grupo e veja o que o coordenador de fato selecionou:

kafka-consumer-groups.sh --bootstrap-server broker:9092 \
  --describe --group orders-svc --state

A coluna ASSIGNMENT-STRATEGY mostra range ou cooperative-sticky. Range significa que toda reinicialização ainda para tudo.

Migrar um grupo em produção exige dois bounces rolling, e a ordem importa. No primeiro, defina partition.assignment.strategy com o assignor eager atual seguido de CooperativeStickyAssignor, mantendo o eager em primeiro lugar para que ele continue selecionado enquanto instâncias antigas e novas convivem. No segundo, remova o assignor eager. Fazer tudo de uma vez falha porque um membro que entra no meio do bounce não encontra nenhuma estratégia em comum com os outros e o rebalance dá erro.

Aplicações Kafka Streams já rodam o protocolo cooperativo por meio do próprio assignor, então não há nada a configurar ali. Os workers do Kafka Connect equilibram connectors e tasks com um protocolo cooperativo incremental separado, controlado por connect.protocol, e o padrão o habilita quando todos os workers o suportam.

O trade-off é pequeno. Um rebalance cooperativo leva um pouco mais de tempo de ponta a ponta, porque são dois rebalances em vez de um, e as partições que mudam de dono ficam sem atribuição nessa janela. Em troca, as partições que não mudam nunca param. O número de partições que você escolhe limita quantos consumidores podem dividir o trabalho, e tratamos disso no nosso guia de estratégia de partições.

Como resolver loops de rebalance: o erro REBALANCE_IN_PROGRESS e o estado PreparingRebalance

"The group is rebalancing, so a rejoin is needed" é a mensagem associada ao código de erro REBALANCE_IN_PROGRESS. O coordenador a retorna para um consumidor cuja requisição carrega uma generation que não é mais a atual — na maioria das vezes, um heartbeat, sync ou commit de offset enviado depois que o grupo passou para PreparingRebalance. Sozinha, ela não é uma falha; o cliente volta ao grupo e o grupo se estabiliza. Vira um problema quando se repete a cada poucos segundos, o grupo nunca chega a Stable e o lag sobe. O broker coordenador registra uma linha correspondente "Preparing to rebalance group ... (reason: ...)", e esse campo reason é a forma mais rápida de saber qual dos casos abaixo está acontecendo.

1. max.poll.interval.ms ultrapassado. O consumidor está vivo, mas demorou demais entre polls e foi removido. Como confirmar: os logs do consumidor dizem "consumer poll timeout has expired" e o reason do broker cita a saída de um membro. Como corrigir: reduza max.poll.records até que o processamento de um lote no pior caso caiba no intervalo e só aumente max.poll.interval.ms se o p99 ainda não couber.

2. session.timeout.ms baixo demais para pausas de GC ou para a rede. A thread de heartbeat trava ou os pacotes dela atrasam, e o membro é expulso. Como confirmar: o reason do broker diz "heartbeat expiration", os logs de GC mostram pausas próximas do timeout e não há mensagem de poll timeout. Como corrigir: aumente session.timeout.ms dentro do limite de group.max.session.timeout.ms do broker e resolva a pausa. Produtores na mesma JVM mostram sintomas relacionados, tratados em causas e correções de timeout de produtor.

  • 3. Consumidores escalando em loop. Um autoscaler adiciona réplicas quando o lag sobe, o lag cai, ele as remove, e o lag sobe de novo. Cada evento de escala é um rebalance. Como confirmar: descrever o grupo com --members mostra um número de membros que muda a cada minuto e coincide com eventos de deploy. Como corrigir: adicione uma janela de estabilização para a redução de escala, limite as réplicas ao número de partições e escale com base em um sinal mais suave do que o lag bruto. Como medir o lag corretamente está no nosso guia de consumer lag.
  • 4. Membership estática não está em uso. Sem group.instance.id, um deploy rolling de dez pods são dez saídas e dez entradas. Com ele, um pod que volta dentro do session timeout retoma a atribuição antiga sem rebalance. Como confirmar: --members --verbose mostra member ids gerados que mudam a cada reinicialização. Como corrigir: defina um instance id estável por pod.
  • 5. Mudança de coordenador ou de broker. A partição de __consumer_offsets que hospeda o grupo mudou de broker, o grupo foi recarregado e todos os membros tiveram de redescobrir o coordenador e voltar ao grupo. Como confirmar: os logs do broker mostram "Loading group metadata" em um novo broker, e o horário coincide com um restart ou uma eleição de líder. Como corrigir: nada no cliente. Um rebalance por bounce de broker é esperado; mudanças repetidas de coordenador significam que o próprio cluster está instável.

As três propriedades que acabam com a maioria desses loops:

max.poll.records=100
group.instance.id=orders-svc-${POD_ORDINAL}
partition.assignment.strategy=org.apache.kafka.clients.consumer.CooperativeStickyAssignor

Aplicamos essas correções para clientes corporativos no suporte 24/7 para Kafka, com metas de resposta a partir de 15 minutos, conforme o plano, e desenhamos os grupos dessa forma desde o início nos projetos de consultoria em Kafka.

Este é o quarto de dez passos do guia de operações do Kafka, que apresenta as decisões operacionais na ordem em que elas surgem em um ambiente de produção.

Perguntas frequentes

O que dispara um rebalance de consumer group no Kafka?

Um consumidor entrando, saindo de forma limpa ou sendo declarado morto pelo coordenador do grupo — seja por heartbeats perdidos além de session.timeout.ms, seja por ultrapassar max.poll.interval.ms entre polls. Uma mudança no número de partições de um tópico assinado também dispara um rebalance.

Por que o rebalanceamento causa latência e acúmulo de mensagens?

Porque é uma barreira de sincronização. Os consumidores param de consumir enquanto o grupo se reagrupa e espera uma nova atribuição, então o membro mais lento define a pausa para todos. Nada é processado nessa janela e o lag se acumula.

O que é rebalanceamento cooperativo no Kafka?

Um protocolo incremental que revoga apenas as partições que de fato estão mudando de dono, permitindo que os consumidores continuem processando todo o resto. O rebalanceamento eager revoga todas as partições de todos os consumidores, por menor que seja a mudança.

Como acabar com rebalances frequentes no Kafka?

Descubra qual relógio está expirando. Se os lotes demoram demais, reduza max.poll.records e aumente max.poll.interval.ms para além do pior caso. Se a causa são reinicializações, use membership estática. Depois, passe para o cooperative sticky assignor, para que os rebalances restantes fiquem mais baratos.

O que é membership estática do grupo (static membership)?

Um group.instance.id estável por consumidor, que permite ao coordenador reconhecer um membro que está reiniciando e devolver as partições anteriores dele sem rebalance, desde que ele volte dentro do session timeout.

Qual estratégia de atribuição de partições devo usar?

CooperativeStickyAssignor para a maioria das cargas de trabalho — ele minimiza tanto a movimentação de partições quanto a interrupção causada pelo rebalance. Migre para ele ao longo de dois deploys rolling, em vez de mudar a configuração de uma só vez.

Adicionar partições dispara um rebalance no Kafka?

Sim. Aumentar o número de partições de um tópico assinado faz o grupo redistribuir as atribuições, então trate mudanças de partições como uma operação agendada, e não como algo rotineiro.

Um rebalance do Kafka é a mesma coisa que reatribuir partições entre brokers?

Não, e o vocabulário compartilhado causa muita confusão. Um rebalance de consumer group redistribui partições entre consumidores. Mover réplicas de partições entre brokers é a reatribuição de partições (partition reassignment) — uma operação de cluster separada, com ferramentas e riscos diferentes.

Por que o meu consumer group do Kafka fica rebalanceando o tempo todo?

Pela nossa experiência, as causas, em ordem, são: o processamento de um lote do poll leva mais tempo do que max.poll.interval.ms; session.timeout.ms é curto demais para as pausas de GC da JVM ou para a rede; um autoscaler está adicionando e removendo consumidores em loop; os consumidores reiniciam sem um group.instance.id, então cada deploy vira uma saída mais uma entrada; ou o coordenador do grupo mudou de broker. O campo reason na linha de log "Preparing to rebalance group" do broker coordenador diz qual delas é. Descreva o grupo com --state para ver se ele chega a ficar Stable.

Como evitar que um rebalance do Kafka cause indisponibilidade?

Três configurações eliminam a maior parte do problema. Mude o grupo para CooperativeStickyAssignor, para que apenas as partições que estão mudando de dono fiquem pausadas, usando a migração em dois bounces. Dê a cada consumidor um group.instance.id estável, para que reinicializações dentro do session timeout não disparem rebalance nenhum. Limite max.poll.records, para que um lote lento não faça um consumidor saudável ser expulso. Depois, ataque a rotatividade na origem: estabilize o autoscaling e mantenha o número de réplicas igual ou menor que o número de partições. Um grupo bem configurado só deveria rebalancear quando você muda o tamanho dele de propósito.

Fontes

Scott Sternloff

Autor

Scott SternloffArquiteto corporativo sênior

Arquiteto corporativo sênior na AceMQ. Escreve a cobertura técnica deste blog: arquitetura, clustering e migrações de RabbitMQ, Kafka e Redis.

Guias, comparativos e pesquisas

Aprofunde-se em Kafka

Consulta gratuita

Um olhar especializado sobre seu cluster Kafka

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