On this page
Um rebalance no Kafka é o processo de redistribuir partições entre os consumidores de um grupo. É desencadeado sempre que a composição do grupo muda — um consumidor entra, sai ou é declarado morto — ou quando muda o número de partições de um tópico subscrito. Um grupo saudável rebalanceia de vez em quando e durante 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 débito.
O rebalanceamento do Kafka não é, em si, uma falha. É a forma como o Apache Kafka distribui partições pelos consumidores e mantém o trabalho equilibrado à medida que uma implementação escala. Perceber como funciona o rebalanceamento do Kafka é importante porque os problemas surgem quando ele dispara com muito mais frequência do que a carga de trabalho justifica.
Vale a pena perceber o mecanismo, porque quase todas as correções são alterações à configuração do consumidor, e não algo que se faça no cluster.
O que desencadeia 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 que arranca depois de uma implementação. É esperado — quando um novo consumidor entra no grupo, o coordenador distribui as partições pelos consumidores que já estão em execução.
Um consumidor sai de forma limpa. Um encerramento controlado que envia um pedido de saída. Também é esperado. Sempre que um consumidor entra ou sai, segue-se 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 desapareceu, o que acontece quando se esgota um de dois temporizadores:
session.timeout.ms(predefinição de 45 segundos). O consumidor envia heartbeats numa thread em segundo plano a cadaheartbeat.interval.ms(predefinição de 3 segundos). Se falharem heartbeats suficientes, o coordenador expulsa-o. Isto deteta falhas reais, partições de rede e pausas de GC longas.max.poll.interval.ms(predefinição de 5 minutos). O intervalo entre chamadas sucessivas apoll()na thread principal. Os heartbeats continuam a fluir na thread em segundo plano, pelo que o consumidor parece vivo — mas, se a aplicação demorar demasiado a processar um lote, o coordenador expulsa-o na mesma.
Este segundo temporizador está na origem da maioria dos rebalances inexplicáveis em produção. O consumidor não falhou. Está apenas a processar devagar, e o Kafka não consegue distinguir um consumidor lento de um bloqueado.
O número de partições muda. Quando são adicionadas novas partições a um tópico do Kafka, segue-se uma nova atribuição. As alterações de subscrição têm o mesmo efeito.
Os dois últimos são eventos de rebalance que preferiria não ter. Desencadear um rebalance no Kafka custa o mesmo, seja qual for a causa, e a atividade de rebalance desnecessária é o que transforma um consumer group funcional num grupo paralisado.
O que acontece realmente durante um rebalance do Kafka?
Todos os consumidores do grupo deixam de consumir, têm de voltar a juntar-se ao grupo e aguardam antes de poderem retomar. O líder do grupo — um dos consumidores, e não um broker do Kafka — envia um pedido ao coordenador do grupo, calcula a forma como as partições são atribuídas e distribui o resultado. As partições são primeiro revogadas e depois novamente distribuídas — e o consumidor que fica com cada partição pode mudar a cada ronda.
A propriedade importante é que se trata de uma barreira de sincronização: todos os consumidores de um consumer group avançam em conjunto, e o membro mais lento dita o ritmo. Um consumidor que demore trinta segundos a voltar ao grupo obriga o grupo inteiro a esperar trinta segundos. Não há processamento de mensagens durante o rebalanceamento, pelo que a acumulação 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 anda atrás de um lag crescente, e não dos rebalances que o provocam, diagnosticar o consumer lag do Kafka trata o lado dos sintomas.
Rebalanceamento eager versus cooperativo
O protocolo de rebalance do Kafka tem duas gerações, e a que estiver a usar altera 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 que lhe estão atribuídas antes de ser calculada a nova atribuição. Mesmo que a redistribuição mova apenas duas partições em duzentas, tudo para. A pausa cresce com a dimensão do grupo e com o tempo de reentrada, e não com o que realmente mudou.
O rebalanceamento incremental revoga apenas as partições que mudam efetivamente de dono. Os consumidores continuam a processar tudo o que mantêm. O protocolo de rebalanceamento cooperativo corre em duas rondas mais leves em vez de uma pesada, pelo que o impacto do rebalance cresce com a dimensão da alteração, e não com o número de membros. Esta abordagem cooperativa incremental é a que a maioria dos ambientes devia estar a usar.
Está disponível desde o Kafka 2.4 e nem sempre é a predefinição num 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 isto e implementar. Passar de eager para cooperativo exige uma atualização rolling em duas fases — primeiro, implemente com as duas estratégias listadas, para que o grupo chegue a acordo; depois, remova a eager numa segunda passagem. Alterá-la de uma só vez num grupo em execução faz falhar o rebalance.
As releases mais recentes vão ainda mais longe. O novo protocolo de rebalance de consumidores passa o cálculo da atribuição para o broker e elimina por completo a barreira de sincronização global, pelo que os consumidores deixam de parar todos ao mesmo tempo. Este novo protocolo atingiu a disponibilidade geral no Apache Kafka 4.0. Se estiver numa release recente, vale a pena avaliá-lo — mas a maioria dos ambientes de produção ainda não chegou lá, e o sticky assignor proporciona hoje a maior parte do benefício.
Estratégias de atribuição de partições
| Assignor | Comportamento | Custo do rebalance |
|---|---|---|
RangeAssignor | Intervalos contíguos por tópico | Eager; pode distribuir de forma desigual entre vários tópicos |
RoundRobinAssignor | Distribuição uniforme por todas as partições | Eager; redistribui tudo |
StickyAssignor | Distribuição uniforme, preservando a atribuição anterior sempre que possível | Eager, mas move menos partições |
CooperativeStickyAssignor | Sticky, e revoga apenas o que muda de dono | Incremental — o que se pretende |
A estabilidade da atribuição (stickiness) importa para além da própria pausa. Quando um consumidor mantém as mesmas partições de tópico ao longo de um rebalance, mantém o estado local aquecido — caches, agregações em curso, state stores do Kafka Streams. Baralhar sem necessidade deita isso fora, e o custo de recuperação ultrapassa muitas vezes o do próprio rebalance.
Se utiliza Spring Kafka ou outra framework sobre o cliente, isto é definido através da mesma propriedade subjacente — a framework não altera as estratégias que tem à disposição.
A tempestade de rebalances no Kafka: porque nunca recupera sozinha
Os problemas de rebalanceamento que trazem as pessoas até nós seguem quase sempre o mesmo padrão:
- O processamento abranda — uma API a jusante degrada-se ou um lote fica maior.
- Um consumidor excede
max.poll.interval.mse é expulso. - O grupo rebalanceia. Todos param.
- A acumulação cresce durante a pausa.
- Na retoma, cada consumidor vai buscar um lote completo perante uma acumulação maior e demora mais tempo a processá-lo.
- Outro consumidor excede o intervalo. Volte ao passo 3.
O débito de processamento cai a pique enquanto o cluster em si continua saudável.
Nunca recupera sozinha, porque cada novo rebalance do Kafka torna o seguinte mais provável — e é exatamente por isso que as equipas começam a investigar o cluster, e não a forma como configuram o consumidor.
Quebrar o ciclo é normalmente uma questão de fazer os lotes terminarem dentro do intervalo:
- Reduza
max.poll.records. A alteração isolada mais eficaz. Menos registos por poll significam menos tempo entre polls. Comece por reduzi-lo para metade. - Aumente
max.poll.interval.mspara que exceda realmente 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 ciclo de poll é o sítio errado para ela.
- Não aumente
session.timeout.mspara resolver isto. É outro temporizador e não ajuda — apenas atrasa a deteção de consumidores realmente mortos.
Membership estática
Onde os consumidores reiniciam com regularidade — implementações rolling no Kubernetes, o caso mais óbvio —, isto impede que o reinício desencadeie sequer um rebalance.
Atribua a cada consumidor um group.instance.id estável. Num reinício dentro da janela de timeout, o coordenador reconhece o membro que regressa e devolve-lhe as partições anteriores sem redistribuir nada:
group.instance.id=consumer-3
session.timeout.ms=45000O compromisso é claro: um membro realmente morto só é substituído quando a sua sessão expira, pelo que as suas partições ficam por consumir durante essa janela. Antes de a ativar, decida se o rebalance é necessário no reinício. Defina o timeout de modo a exceder com folga o tempo do seu reinício rolling, e nada mais.
Há também uma configuração do lado do broker que convém conhecer para o arranque. group.initial.rebalance.delay.ms (predefinição de 3 segundos) faz o coordenador esperar um pouco antes do primeiro rebalance, para que os consumidores que arrancam em conjunto formem um único grupo, em vez de rebalancearem repetidamente à medida que cada um chega. É um pormenor que elimina muito ruído nas implementações em Kubernetes.
O que monitorizar
Acompanhe três coisas, e acompanhe-as em conjunto:
- Taxa de rebalances. O próprio sinal. Tudo o que vá além do ocasional merece investigação — e um consumidor preso num ciclo de rebalance aparece aqui primeiro.
- Duração dos rebalances. Uma duração crescente significa que os consumidores demoram a voltar ao grupo — muitas vezes, o mesmo processamento lento que desencadeou o rebalance.
- Consumer lag durante os rebalances. Confirma se as pausas estão de facto a custar débito ou se são suficientemente curtas para não terem importância.
Um consumer group que passa por um rebalance do Kafka algumas vezes por dia, à volta das implementações, está bem. Um que rebalanceia a cada poucos minutos está a dizer que max.poll.interval.ms está a ser excedido, e nenhum ajuste ao cluster vai mudar isso.
Está a ver tempestades de rebalance ou pausas inexplicáveis nos consumidores? Estão quase sempre na configuração
do consumidor, e não no cluster, e é por isso que as métricas do broker parecem limpas enquanto o débito
cai a pique. A AceMQ realiza avaliações estruturadas de Kafka que as encontram —
Se uma única pessoa concentra todo este conhecimento, isso é um risco de recursos humanos, e não de Kafka: quanto custa realmente dar suporte ao Kafka internamente.
Rebalanceamento cooperativo na prática: como o verificar, como migrar e o que fazem o Streams e o Connect
Range, round-robin e o sticky assignor original usam todos o protocolo eager. Perante qualquer alteração na composição, o coordenador passa o grupo para PreparingRebalance, cada consumidor revoga todas as partições que detém, todos voltam a juntar-se 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 decorre em duas fases. Na primeira, o líder calcula a nova atribuição e cada consumidor revoga apenas as partições que deixam de ser suas, enquanto continua a fazer poll e commit de tudo o resto. Segue-se de imediato um segundo rebalance, no qual as partições libertadas passam para os novos donos. O único assignor do lado do cliente que usa este protocolo é o CooperativeStickyAssignor.
A maioria dos grupos para os quais somos chamados está a correr em eager sem o saber. Primeiro, a configuração do consumidor: partition.assignment.strategy é uma lista e, nos clientes recentes, a lista predefinida contém tanto range como cooperative-sticky. O coordenador seleciona uma estratégia suportada por todos os membros, pelo que a predefinição acaba por cair em range. Segundo, descreva o grupo e veja o que o coordenador selecionou de facto:
kafka-consumer-groups.sh --bootstrap-server broker:9092 \
--describe --group orders-svc --stateA coluna ASSIGNMENT-STRATEGY mostra range ou cooperative-sticky. Range significa que cada reinício continua a parar tudo.
Migrar um grupo em produção exige dois reinícios 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 continue selecionado enquanto coexistem instâncias antigas e novas. No segundo, remova o assignor eager. Fazê-lo de uma só vez falha, porque um membro que entra a meio do reinício não encontra nenhuma estratégia em comum com os outros e o rebalance termina em erro.
As aplicações Kafka Streams já correm o protocolo cooperativo através do seu próprio assignor, pelo que não há nada a configurar aí. Os workers do Kafka Connect equilibram connectors e tasks com um protocolo cooperativo incremental separado, controlado por connect.protocol, e a predefinição ativa-o quando todos os workers o suportam.
O compromisso é pequeno. Um rebalance cooperativo demora um pouco mais 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 durante essa janela. Em contrapartida, as partições que não mudam nunca param. O número de partições escolhido limita quantos consumidores podem repartir o trabalho, tema que tratamos no nosso guia de estratégia de partições.
Como resolver ciclos 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 devolve-a a um consumidor cujo pedido traz uma generation que já não é a atual — na maioria das vezes, um heartbeat, um sync ou um commit de offset enviado depois de o grupo ter passado para PreparingRebalance. Por si só, não é uma falha; o cliente volta a juntar-se e o grupo estabiliza. Torna-se um problema quando se repete a cada poucos segundos, o grupo nunca chega a Stable e o lag sobe. O broker coordenador regista uma linha correspondente "Preparing to rebalance group ... (reason: ...)", e esse campo reason é a forma mais rápida de saber qual dos casos seguintes está a acontecer.
1. max.poll.interval.ms excedido. O consumidor está vivo, mas demorou demasiado entre polls e foi removido. Como confirmar: os logs do consumidor dizem "consumer poll timeout has expired" e o reason do broker refere 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 continuar a não caber.
2. session.timeout.ms demasiado baixo para as pausas de GC ou para a rede. A thread de heartbeat bloqueia ou os seus pacotes atrasam-se, 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. Os produtores na mesma JVM apresentam sintomas relacionados, tratados em causas e correções de timeout do produtor.
- 3. Consumidores a escalar em ciclo. Um autoscaler adiciona réplicas quando o lag sobe, o lag desce, ele remove-as e o lag volta a subir. Cada evento de escala é um rebalance. Como confirmar: descrever o grupo com
--membersmostra um número de membros que muda de minuto para minuto e coincide com eventos de implementação. Como corrigir: acrescente 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 num sinal mais suave do que o lag em bruto. A forma correta de medir o lag está no nosso guia de consumer lag. - 4. Membership estática não utilizada. Sem
group.instance.id, uma implementação rolling de dez pods corresponde a dez saídas e dez entradas. Com ele, um pod que regressa dentro do session timeout retoma a atribuição anterior sem rebalance. Como confirmar:--members --verbosemostra member ids gerados que mudam a cada reinício. Como corrigir: defina um instance id estável por pod. - 5. Mudança de coordenador ou de broker. A partição de
__consumer_offsetsque aloja o grupo mudou de broker, o grupo foi recarregado e todos os membros tiveram de redescobrir o coordenador e voltar a juntar-se. Como confirmar: os logs do broker mostram "Loading group metadata" num novo broker, e o momento coincide com um reinício ou uma eleição de líder. Como corrigir: nada no cliente. Um rebalance por cada reinício 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 destes ciclos:
max.poll.records=100
group.instance.id=orders-svc-${POD_ORDINAL}
partition.assignment.strategy=org.apache.kafka.clients.consumer.CooperativeStickyAssignorAplicamos estas correções para clientes empresariais no âmbito do suporte 24/7 para Kafka, com objetivos de resposta a partir de 15 minutos, consoante o plano, e desenhamos os grupos desta 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 pela ordem em que surgem num ambiente de produção.
Perguntas frequentes
O que desencadeia um rebalance de um consumer group no Kafka?
Um consumidor que entra, que sai de forma limpa ou que é declarado morto pelo coordenador do grupo — seja por heartbeats em falta para lá de session.timeout.ms, seja por exceder max.poll.interval.ms entre polls. Uma alteração do número de partições de um tópico subscrito também desencadeia um rebalance.
Porque é que o rebalanceamento provoca latência e acumulação de mensagens?
Porque é uma barreira de sincronização. Os consumidores deixam de consumir enquanto o grupo se volta a juntar e aguarda uma nova atribuição, pelo que o membro mais lento define a pausa para todos. Nada é processado nessa janela e o lag acumula-se.
O que é o rebalanceamento cooperativo no Kafka?
Um protocolo incremental que revoga apenas as partições que mudam efetivamente de dono, permitindo que os consumidores continuem a processar tudo o resto. O rebalanceamento eager revoga todas as partições de todos os consumidores, por menor que seja a alteração.
Como acabar com rebalances frequentes no Kafka?
Descubra qual dos temporizadores está a expirar. Se os lotes demoram demasiado, reduza max.poll.records e aumente max.poll.interval.ms para lá do pior caso. Se a causa são os reinícios, use membership estática. Depois, passe para o cooperative sticky assignor, para que os rebalances restantes fiquem mais baratos.
O que é a membership estática do grupo (static membership)?
Um group.instance.id estável por consumidor, que permite ao coordenador reconhecer um membro que está a reiniciar e devolver-lhe as partições anteriores sem rebalance, desde que regresse dentro do session timeout.
Que estratégia de atribuição de partições devo usar?
CooperativeStickyAssignor para a maioria das cargas de trabalho — minimiza tanto a movimentação de partições como a perturbação causada pelo rebalance. Migre para ele ao longo de duas implementações rolling, em vez de alterar a configuração de uma só vez.
Adicionar partições desencadeia um rebalance no Kafka?
Sim. Aumentar o número de partições de um tópico subscrito obriga o grupo a redistribuir as atribuições, pelo que as alterações de partições devem ser tratadas como uma operação agendada, e não como algo rotineiro.
Um rebalance do Kafka é o mesmo que reatribuir partições entre brokers?
Não, e o vocabulário partilhado provoca 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 distinta, com ferramentas e riscos diferentes.
Porque é que o meu consumer group do Kafka está sempre a rebalancear?
Pela nossa experiência, as causas, por ordem, são: processar um lote de poll demora mais do que max.poll.interval.ms; session.timeout.ms é demasiado curto para as pausas de GC da JVM ou para a rede; um autoscaler está a adicionar e a remover consumidores em ciclo; os consumidores reiniciam sem um group.instance.id, pelo que cada implementação é uma saída mais uma entrada; ou o coordenador do grupo mudou de broker. O campo reason da linha de log "Preparing to rebalance group" do broker coordenador indica qual delas é. Descreva o grupo com --state para ver se chega alguma vez ao estado Stable.
Como evitar que um rebalance do Kafka provoque indisponibilidade?
Três configurações eliminam a maior parte do problema. Mude o grupo para CooperativeStickyAssignor, para que só as partições que mudam de dono fiquem em pausa, usando a migração em dois reinícios. Atribua a cada consumidor um group.instance.id estável, para que os reinícios dentro do session timeout não desencadeiem qualquer rebalance. Limite max.poll.records, para que um lote lento não leve à expulsão de um consumidor saudável. Depois, ataque a rotação na origem: estabilize o autoscaling e mantenha o número de réplicas igual ou inferior ao número de partições. Um grupo bem configurado só deve rebalancear quando se altera deliberadamente a sua dimensão.
Fontes
Guias, comparações e estudos

