Elasticsearch e OpenSearch em produção: shards, heap e o cluster amarelo

Cluster de busca é fácil de subir e difícil de manter saudável. A primeira instalação funciona bem, a equipe fica satisfeita, e alguns meses depois aparece o conjunto conhecido de sintomas: cluster amarelo que ninguém sabe resolver, consultas lentas, nós saindo do cluster, disco cheio e reinícios que demoram meia hora.

Quase tudo isso vem de três decisões tomadas no começo sem informação: quantos shards criar, quanto de memória dar ao processo e o que aquele cluster deveria armazenar.

Os conceitos em cinco linhas

• Índice é o conjunto de documentos, dividido em shards.
• Shard primário guarda uma fatia dos dados. O número é definido na criação do índice e, na prática, não muda depois.
• Réplica é a cópia de um shard primário, em outro nó. Dá redundância e capacidade de leitura.
• Nó é uma instância; pode acumular papéis — mestre, dado, coordenação, ingestão.
• Estado do cluster: verde (tudo alocado), amarelo (primários alocados, alguma réplica não), vermelho (algum primário não alocado).

O cluster amarelo, explicado de uma vez

É a dúvida mais frequente, e a resposta quase sempre é a mesma.

Amarelo significa que os dados estão íntegros e servindo, mas alguma réplica não está alocada. Você está funcionando sem redundância naquele shard.

A causa mais comum, com folga: o índice pede uma réplica e o cluster tem um nó só. Réplica jamais é alocada no mesmo nó do primário — seria inútil para redundância. Cluster de um nó com índice pedindo réplica fica amarelo para sempre.

As soluções, conforme o caso:

• Ambiente de desenvolvimento com um nó: configure zero réplicas. O amarelo desaparece e você para de ignorar um alerta que deveria significar algo.
• Produção: tenha ao menos três nós de dados e uma réplica. É o mínimo para sobreviver à perda de um nó.
• Amarelo repentino em cluster que era verde: um nó saiu. Investigue por quê antes de tudo — costuma ser memória, disco ou rede.
• Amarelo persistente com nós suficientes: o cluster está recusando alocação por algum motivo. As causas típicas são disco acima do limiar de proteção, regras de alocação por atributo que não podem ser satisfeitas, ou incompatibilidade de versão entre nós.

Sobre o disco: o cluster tem limiares que param de alocar shards e, em nível mais alto, movem shards para fora do nó. Ultrapassar o limiar mais alto também torna os índices somente leitura como proteção — e essa é a causa do "parou de indexar sem erro aparente".

Shards: o erro mais caro e o mais comum

A tentação é criar muitos shards "para escalar depois". É o contrário do que acontece.

Cada shard é um índice invertido completo, com custo fixo de memória, de descritores de arquivo e de metadados no estado do cluster. Milhares de shards pequenos consomem memória, tornam o estado do cluster pesado, deixam a recuperação lenta e degradam as consultas — porque cada consulta precisa tocar todos os shards do índice e juntar os resultados.

As orientações práticas:

• Tamanho alvo de shard entre 10 e 50 GB. Menor que isso é desperdício; muito maior torna recuperação e realocação demoradas.
• Comece com poucos shards. Índice de 30 GB não precisa de dez shards.
• Limite o número de shards por nó em relação à memória disponível. Há uma proporção recomendada, e ultrapassá-la é o caminho mais direto para instabilidade.
• Réplicas são ajustáveis a quente, shards primários não. Erre para menos nos primários; você pode adicionar réplicas depois.

Para dados que crescem com o tempo — log, métrica, evento —, o padrão correto é índice por período com rollover automático por tamanho ou idade, e política de ciclo de vida que move índices antigos para armazenamento mais barato e os remove ao fim da retenção. Um índice único e eterno é o desenho que garante problema.

Memória: metade, e não mais que o limite

Dimensionamento de memória tem duas regras que parecem estranhas e são fundamentais.

Regra 1: dê ao processo cerca de metade da memória da máquina. A outra metade fica para o cache de arquivos do sistema operacional, que é o que faz a busca ser rápida. Dar 90% da memória ao processo deixa o cluster mais lento, não mais rápido.

Regra 2: não ultrapasse o limite em torno de 30 GB. Acima disso, a máquina virtual do Java perde uma otimização de ponteiros e passa a usar mais memória para guardar a mesma coisa — você aumenta o número e obtém menos capacidade efetiva, além de pausas de coleta de lixo mais longas.

Consequência prática: um servidor com 128 GB de RAM não deve rodar um nó com 64 GB de memória de processo. Rode dois nós de 30 GB nele, ou aceite usar 30 GB e deixar o resto para o cache de arquivos.

Complementos que importam:

• Desabilite a área de troca. Nada degrada um cluster de busca como paginação.
• Memória mínima e máxima iguais, evitando redimensionamento do heap em execução.
• Monitore a pressão de memória e as pausas de coleta. Pausas longas fazem o nó ser considerado morto pelo cluster, e o nó sai — gerando o cluster amarelo que abriu este artigo.

O papel dos nós

Em cluster pequeno, todos os nós fazem tudo. A partir de um certo tamanho, separar papéis estabiliza:

• Nós mestres dedicados, em número ímpar (três), pequenos, que só cuidam do estado do cluster. Isso impede que carga pesada de busca ou de indexação derrube a coordenação — que é a causa mais comum de instabilidade em cluster médio.
• Nós de dados, com disco rápido e memória.
• Nós de coordenação, opcionais, que recebem as consultas e agregam resultados.

A separação dos mestres é o investimento de melhor retorno em estabilidade, e custa pouco — são máquinas pequenas.

Índice de busca não é banco de dados

Vale repetir, porque o erro é caro e comum: o dado canônico não deve morar apenas no cluster de busca.

Motivos concretos:

• Não há transação nem garantia de consistência forte.
• A busca é quase em tempo real — documento indexado não fica visível instantaneamente.
• Reindexação é uma operação frequente — mudança de mapeamento, atualização de versão maior. Ela exige reconstruir o índice a partir da fonte. Se a fonte é o próprio índice, você está preso.
• Recuperação após perda é bem mais simples reindexando da fonte do que restaurando.

O desenho correto: banco transacional como fonte da verdade, índice alimentado a partir dele, com capacidade de reconstrução completa a qualquer momento. Testar essa reconstrução vale tanto quanto testar backup.

Mapeamento: a decisão que trava depois

O mapeamento define os tipos dos campos, e não pode ser alterado para campos existentes. Mudar exige criar índice novo e reindexar.

Cuidados que evitam retrabalho:

• Defina o mapeamento explicitamente em vez de deixar o sistema inferir. Inferência erra tipo e cria campos que você não queria indexar.
• Desabilite a indexação de campos que você só quer armazenar. Cada campo indexado custa espaço e memória.
• Cuidado com explosão de campos. Documentos com chaves dinâmicas — nomes de campo vindos de dados — podem gerar milhares de campos no mapeamento e inviabilizar o índice. Há um limite, e atingi-lo é um incidente.
• Use apelidos de índice na aplicação. Assim, reindexar passa a ser: criar o índice novo, preencher, trocar o apelido. Sem apelido, cada reindexação exige mudança de aplicação.

O apelido é a decisão de cinco minutos que economiza semanas depois.

Operação: o que monitorar

• Estado do cluster e número de shards não alocados.
• Pressão de memória e pausas de coleta por nó.
• Espaço em disco contra os limiares de proteção, com projeção.
• Latência de busca e de indexação, em percentil alto.
• Fila e rejeições nos pools de execução — rejeição indica que o cluster não está acompanhando a carga.
• Número total de shards por nó.
• Snapshots executados e testados.

E backup: o mecanismo nativo de snapshot para repositório externo é o caminho, com restauração testada. Copiar o diretório de dados de um cluster em execução não produz backup restaurável.

Erros comuns

• Ignorar o cluster amarelo em vez de entender a causa.
• Um nó só com índice pedindo réplica, amarelo permanente.
• Shards demais, pequenos, consumindo memória e degradando consulta.
• Índice único e eterno para dado temporal.
• Dar quase toda a memória ao processo, sem deixar cache de arquivos.
• Ultrapassar o limite de heap e perder a otimização de ponteiros.
• Área de troca habilitada.
• Sem nós mestres dedicados em cluster médio.
• Usar o índice de busca como fonte da verdade.
• Deixar o mapeamento ser inferido automaticamente.
• Explosão de campos por chaves dinâmicas.
• Não usar apelidos, e travar a reindexação.
• Não monitorar rejeições nos pools de execução.
• Backup por cópia de diretório em vez de snapshot.
• Nunca testar a reconstrução do índice a partir da fonte.

Onde a Solvefy/Cloud entra

Cluster de busca é uma das peças que mais aparece mal dimensionada nos ambientes que atendemos. Revisamos e implantamos: número e tamanho de shards adequados ao volume, política de ciclo de vida para dados temporais, memória dimensionada com as duas regras, separação de papéis com mestres dedicados, mapeamento explícito com apelidos, snapshots com restauração testada e monitoramento com os indicadores que realmente antecipam problema. Também revisamos o desenho de alimentação a partir da fonte da verdade e testamos a reconstrução completa.

Seu cluster de busca está amarelo e ninguém sabe por quê? Diagnóstico gratuito, sem compromisso, em solvefy.cloud.

Solvefy/Cloud — Infraestrutura que cresce com você.