Reindexação de fluxos de dados por causa de conflitos de mapeamento

Quando surgem conflitos de mapeamento em campos, sejam eles padrão Elastic Common Schema (ECS) ou específicos da fonte de dados, é necessário reindexar seus dados usando as Ferramentas de Desenvolvimento. Esses conflitos podem impactar negativamente qualquer função subsequente à ingestão, potencialmente causando resultados imprecisos ou impedindo o uso do conjunto de dados completo em recursos como visualizações, dashboards, o app Security e agregações. Esta post do blog detalha as etapas desse processo de reindexação.

O conteúdo deste blog foi desenvolvido e verificado usando as versões 9.2.8 e 8.19.14 do Elastic, juntamente com as versões 2.3.0 e 1.2.0 do Filestream Integration.

Observação importante: dependendo do seu ambiente, algumas etapas podem exigir modificações específicas. Além disso, esteja ciente de que os templates dinâmicos foram removidos do template de componente @package a partir da versão 2.3.3 do Filestream Integration.

Antes de iniciar o processo de reindexação, é importante considerar a alocação de armazenamento atual no seu ambiente. As etapas descritas abaixo envolvem a criação de uma cópia do índice de apoio existente, que estará temporariamente na camada ativa.

Camadas de dados Elasticsearch

• Ativa: a camada ativa é o ponto de entrada do Elasticsearch para dados de série temporal e armazena os dados mais recentes e buscados com frequência. Os nós da camada ativa exigem leituras e gravações rápidas, o que requer mais recursos e armazenamento mais rápido (SSDs). Essa camada é obrigatória e novos índices de fluxo de dados são alocados automaticamente aqui.
• Warm: os dados de séries temporais podem ser movidos para a camada warm quando estiverem sendo consultados com menos frequência do que os dados indexados recentemente na camada ativa. A camada warm normalmente contém dados das últimas semanas. As atualizações ainda são permitidas, mas provavelmente serão raras. Os nós na camada warm geralmente não precisam ser tão rápidos quanto os da camada ativa. Para resiliência, índices na camada warm devem ser configurados para usar uma ou mais réplicas.
• Cold: dados que são pesquisados raramente podem ir da camada warm para a cold. A camada cold, embora ainda pesquisável, prioriza custos de armazenamento menores em detrimento da velocidade de busca. Alternativamente, a camada cold pode armazenar índices regulares com réplicas em vez de snapshots pesquisáveis, permitindo o uso de hardware mais barato para dados antigos sem reduzir o espaço em disco em comparação com a camada warm.
• Frozen: os dados que são consultados com pouca frequência ou que não são mais consultados são movidos da camada cold para a camada frozen, onde permanecem durante o restante do ciclo de vida. Essa camada utiliza um repositório de snapshots e índices parcialmente montados para armazenar e carregar dados, reduzindo o armazenamento local e os custos, ao mesmo tempo em que permite fazer buscas. Buscas na camada frozen geralmente são mais lentas do que na camada cold porque o Elasticsearch pode precisar buscar dados congelados do repositório de snapshots. Recomendamos nós dedicados para a camada frozen.

Pré-requisitos: definir quais campos têm conflitos

Para definir quais campos apresentam conflitos de mapeamento, navegue até Stack Management -> Data Views -> logs-* (a visualização de dados logs-* representa a hierarquia mais alta de dados presentes com o prefixo logs- ). Caso haja algum conflito, será indicado em uma caixa amarela. Você pode clicar em Exibir conflitos ou, na caixa Tipo de campo ao lado da caixa de Busca , selecionar conflito.

Ao clicar no botão amarelo conflito, você verá quais índices estão associados a quais tipos de mapeamento.

Esta situação (em que o campo é mapeado como keyword e long) normalmente ocorre porque os dados foram ingeridos antes de um tipo de mapeamento específico ter sido definido no modelo de componente para o fluxo de dados relevante. Nesses casos, o Elasticsearch tenta definir o mapeamento com base nos templates dinâmicos.

Para determinar qual mapeamento é apropriado para o campo e se ele é um campo ECS, é necessário verificar a referência do campo ECS. Se o campo em questão não for um campo ECS, o seu valor deve ser revisado para determinar o mapeamento correto.

Se um campo, como log.offset neste exemplo, não estiver documentado no ECS, os próximos passos são investigar o valor do campo, definir qual tipo de mapeamento conflitante possui mais índices de suporte e analisar os modelos de componentes dos outros índices.

Normalmente, o tipo de mapeamento associado ao maior número de índices é o correto, mas recomendamos que você verifique o valor do campo em questão para validar isso. Para confirmar a validade de um tipo de mapeamento (por exemplo, long), você também deve verificar se o valor do campo é apropriado para esse tipo. Essa verificação pode ser feita usando o Discover para pesquisar o campo em questão. Revisar outros fluxos de dados que contenham o mesmo campo também pode fornecer confirmação adicional.

Para revisar os valores presentes para o campo com o problema de mapeamento, navegue de volta para o botão amarelo Conflito mencionado anteriormente, clique no botão Conflito, destaque um dos índices de suporte e cole em uma sessão Discover . Sua instrução Kibana Query Language (KQL) deve se parecer com a seguinte captura de tela, incluindo o delimitador de campo _index:.

Configure o novo modelo de componente personalizado para o índice base

Para resolver o conflito de mapeamento no fluxo de dados, primeiro verifique o respectivo template de componente @package. Você encontra isso em Stack Management -> Index Management -> Component Template. Procure o fluxo de dados e selecione o link @package correspondente. Este template contém, por padrão, os mapeamentos dos campos e, embora não seja comum haver incompatibilidade de mapeamento, é possível que o tipo mais adequado passe despercebido.

Revise o modelo para confirmar que ele contém o aninhamento e o mapeamento necessários para o campo em questão. Por exemplo, se o modelo listar log.offset incorretamente como keyword, essa é a origem do problema.

Importante: como modificar @package/managed templates não é recomendado, você deve usar ou criar um modelo de componente @custom para corrigir o tipo de mapeamento (por exemplo, para log.offset) para todos os dados futuros.

• Não recomendamos modificar os modelos @package/managed, pois quando você atualiza a integração para uma versão mais recente, quaisquer alterações feitas no modelo @package serão sobrescritas. É por isso que recomendamos o uso dos modelos @custom.
• Se um fluxo de dados estiver enfrentando conflitos de mapeamento, você precisará adicionar qualquer aninhamento ou mapeamento de campo ausente (ECS e não ECS) ao modelo de componente @custom do fluxo de dados. Crie esse modelo se ele ainda não existir e certifique-se de especificar o tipo correto de mapeamento para o campo.
• Se você tiver vários conflitos no seu data view, aplique todos os mapeamentos ausentes necessários para o fluxo de dados simultaneamente para que a reindexação seja executada uma vez em vez de várias vezes. Ter entradas para digitação correta de dados no modelo de componente @custom garantirá que qualquer ingestão futura de dados siga a mesma diretriz de mapeamento.

Para criar o modelo de componente @custom (ou verificar se ele está em uso e preenchido), navegue até Modelos de Índice, digite o nome do fluxo de dados em questão e clique no modelo @custom apropriado que está sendo usado pelo fluxo de dados. Se o modelo ainda não tiver sido criado, uma caixa amarela aparecerá, permitindo que você crie o modelo pela UI.

A captura de tela abaixo mostra a próxima página após selecionar "Criar modelo de componente". Deixe os padrões como estão na primeira página e clique em Mapeamentos ou Próximo até que você chegue à página Mapeamentos.

Para definir explicitamente o mapeamento de um novo campo que está chegando ou para atualizar um campo com conflito de mapeamento, quando o fluxo de dados é transferido devido à configuração definida na política de ciclo de vida do índice, é necessária uma entrada para o campo onde o conflito existe.

O código abaixo definirá o mapeamento para o campo log.offset no modelo de componente @custom para o fluxo de dados filestream. Repita os passos para adicionar quaisquer campos personalizados ou atualizar os campos necessários do @package com os mapeamentos apropriados, se necessário, para este conjunto de dados. Neste exemplo, ao definir o deslocamento para Long, o tipo de campo será Numeric e o tipo numérico será Long. Clique em Adicionar campo e, em seguida, fora da área para continuar.

Quando todos os campos necessários tiverem sido adicionados, clique para revisar e selecione Criar modelo de componente quando estiver pronto. Todos os novos dados ingeridos a partir desse passo adiante terão log.offset configurados para long.

Criando a nova estrutura de índice de suporte

O novo índice de suporte precisa ter os mapeamentos existentes do modelo de componente do fluxo de dados, assim como o modelo ECS de componente ecs@mappings . O modelo do componente ecs@mappings é aplicado após o componente do fluxo de dados como um complemento para mapeamentos adicionais que provavelmente não foram capturados nos modelos de componentes anteriores.

Navegue até a guia do navegador para os mapeamentos de @package do fluxo de dados. (Vá para to Stack Management -> Index Management -> Component Template -> logs-filestream.generic@package -> Gerenciar -> Editar.) Uma vez lá, clique na seção Revisão, então em Solicitar, e finalmente no botão Copiar à direita. O conteúdo JSON do modelo de componente copiado garantirá que os mapeamentos de campo restantes e as configurações sejam mantidos enquanto atualizamos o mapeamento do campo log.offset. O JSON formará a estrutura de suporte para o novo índice de suporte reindexado.

Importante: se o JSON do modelo não foi copiado e o trabalho foi continuado com a reindexação, o conflito log.offset seria resolvido, mas haveria novos conflitos com a integração, já que a integridade dos mapeamentos atuais não foi mantida, criando trabalho duplo para resolver o problema original.

Abra uma segunda aba do navegador, navegue até as Ferramentas de desenvolvimento e cole o conteúdo copiado. Agora, para limpar o que foi colado:

Modificações na solicitação

1. Nome do índice: substitua _component_template/logs-filestream.generic@package pelo nome do índice de respaldo que você pretende reindexar, adicionando -1 ao final. Por exemplo, use PUT <backing index to reindex>-1.

• A -1 anexada indica uma reindexação e não entra em conflito com as configurações padrão de rollover do ILM, que são baseadas na data de criação do índice.

2. Configurações: remova a "template" de linha (linha 3), assim como a última chave de fechamento para toda a carga útil JSON; a linha 3 deve começar com "settings": {.

• Substitua os conteúdos internos da seção de configurações por "index.codec": "best_compression". Essa ação aplicará a melhor compressão da Elastic ao índice durante a criação.
• Adicione "index.lifecycle.name": "logs", bem como uma linha para "index.lifecycle.rollover_alias": "".
  1. A entrada "index.lifecycle.name": "logs" aplicará a política ILM de logs ao novo índice de apoio. Modifique o nome da política do ILM se você não estiver usando logs.
  2. O "index.lifecycle.rollover_alias": "" está em branco, já que este índice de suporte não será reiniciado, mas a configuração é necessária para evitar erros de rollover do ILM na próxima fase do ILM após a camada ativa.

3. Estrutura: o pedido agora deve incluir tanto uma seção Settings quanto uma seção Mappings. Dentro de "mappings": {, você deve encontrar "dynamic_templates" e uma seção "properties" contendo campos codificados e os mapeamentos.

4. Modificação de modelos dinâmicos: a seção de modelos dinâmicos atuais contém entradas para campos que podem ser substituídos quando os modelos dinâmicos ecs@mappings forem adicionados em seguida, causando redundância e linhas extras que não são necessárias.

• Remova todas as seções do "dynamic_templates" exceto a segunda seção intitulada "_embedded_ecs-data_stream_to_constant": {.
• Repita o mesmo processo descrito acima, reunindo os mapeamentos dinâmicos para o modelo de componente @package, mas desta vez para o modelo de componente ecs@mappings.
  • Pode ser mais fácil copiar todo o conteúdo dos mapeamentos da UI do modelo de componente ecs@mappings, colar na seção de Ferramentas de Desenvolvimento dynamic_templates e remover linhas duplicadas e desnecessárias quando apropriado. Inclua esses conteúdos de configuração de templates dinâmicas após a entrada"_embedded_ecs-data_stream_to_constant": {. A seção dynamic_templates deve ser muito semelhante ao conteúdo de exemplo abaixo no Dev Tools.
• Se dynamic_templates não forem incluídos/removidos por completo, outros campos (veja a captura de tela abaixo) terão mapeamentos duplos: text e keyword versus os mapeamentos apropriados, se a seção dynamic_templates for deixada incluída. O que resta deve ser a seção "properties" abaixo de "mappings". Isso também criará problemas na Data view ao fazer com que os campos sejam mapeados em duplicidade (se ainda não forem mapeados dessa forma) e causará conflitos adicionais de mapeamento.

5. Remoção de metadados: exclua a última seção rotulada "_meta", assim como a seção rotulada "version", caso esteja presente.

6. Formatação: recuar automaticamente as seções restantes e ajustar ou remover quaisquer chaves desnecessárias que possam evitar uma execução bem-sucedida.

7. Mudança de mapeamento: navegue até a seção "properties", encontre "log" e, então, localize "offset" aninhado abaixo. Mude o tipo de keyword para long e remova a entrada da linha (incluindo a vírgula) rotulada "ignore_above": 1024,. Se mais de uma entrada foi adicionada ao modelo de componente @custom criado anteriormente, inclua-as aqui.

Sua visualização do console Dev Tools agora deve ser semelhante ao exemplo fornecido abaixo.

Depois que seu console se assemelhar ao exemplo (com quaisquer campos personalizados adicionais incluídos e valores personalizados específicos para o seu ambiente), execute o comando para criar a estrutura do novo índice de apoio, fazendo uma pausa para resolver quaisquer erros que surgirem.

Iniciar processo de reindexação

Com a estrutura do novo índice de suporte criada com sucesso, o próximo passo é reindexar e resolver os conflitos de mapeamento.

Importante: se o índice de suporte que apresenta o conflito de mapeamento for o índice mais recente e for o índice de escrita atual (por exemplo, o número final do índice de suporte for -000001), o fluxo de dados precisa ser alternado. É necessário alternar o fluxo de dados, pois o índice de escrita atual, que recebe documentos inseridos nele, é um índice de suporte em tempo real e não pode ser modificado.

Com o mapeamento correto de campos agora aplicado ao índice de escrita mais recente via o modelo de componente @custom criado anteriormente, todos os novos documentos refletirão essa mudança.

Isso é realizado executando o seguinte:

Por exemplo:

A reindexação envolve copiar os dados de um índice existente para um novo índice, mantendo a mesma convenção de nomenclatura, geralmente para aplicar as alterações necessárias. Essas modificações podem incluir atualizações em um modelo de componente ou a adição de um novo pipeline de ingestão para que os dados sejam processados.

Em seguida, os dados serão copiados do índice de apoio que possui os mapeamentos incorretos para um novo índice de apoio. O índice original de suporte foi revertido, o que significa que nenhum novo documento pode ser adicionado a ele. O novo índice de apoio seguirá a mesma convenção de nomenclatura, que preserva a visibilidade e integridade dos dados ao aplicar a política correta de ILM, mas incluirá um sufixo -1 para indicar que foi reindexado.

Ajuste os nomes dos índices conforme necessário e cole o código a seguir no console. Ao incluir wait_for_completion=false, você pode acompanhar o progresso da cópia de documentos, o que ajuda a estimar o tempo restante de reindexação. Sem essa configuração, você não pode rastrear o status usando o comando GET _tasks abaixo e só poderá verificar a contagem de documentos no índice de backup mais recente usando GET <backing index name>-1/_count.

Importante: se surgirem problemas durante o processo de reindexação, não execute novamente o comando reindex; fazer isso reiniciará o processo e criará registros duplicados no índice terminando com -1. Se for necessário reiniciar, primeiro exclua o índice com o sufixo -1 e depois execute o comando PUT anterior para recriar a nova shell de índice de backup.

Após a execução, a resposta incluirá um ID de tarefa. Você pode monitorar o progresso do reindex usando esse ID com o comando: GET _tasks/<task ID>.

A duração da reindexação depende do volume de dados no índice original. A conclusão pode ser rastreada procurando por "completed": true ao executar o comando GET, que deve gerar uma saída semelhante.

GET _tasks/<task ID>

Com o processo de reindexação concluído para a contagem de documentos, a próxima etapa é verificar se os mapeamentos para o novo índice de suporte e o campo específico em questão estão corretos.

Por exemplo:

Você pode verificar se o mapeamento para log.offset está conforme mostrado abaixo. Para confirmar que outros campos têm apenas uma única entrada de mapeamento (não ambos text e keyword), compare-os com um campo que não fazia parte da seção de template dinâmico no comando PUT anterior.

Se o índice de backup que está sendo reindexado tiver um grande número de documentos, verifique o status desses documentos sendo copiados para o novo índice de backup; isso pode ser feito pelos dois comandos a seguir no Dev Tools para comparar as contagens.

GET .ds-logs-filestream.generic-default-2026.04.14-000001/_count

GET .ds-logs-filestream.generic-default-2026.04.14-000001-1/_count

Depois que as contagens forem verificadas como correspondentes e os mapeamentos corretos estiverem presentes, atualize o fluxo de dados para incluir o novo índice de apoio, evitar um índice de apoio órfão na gestão de índices, onde a política ILM nunca será aplicada ao índice de apoio.

• O retorno deve ser uma confirmação de verdadeiro, caso a operação seja bem-sucedida.

Verifique se o novo índice de suporte foi adicionado com o seguinte comando, certificando-se de que o ilm_policy esteja correto:

Verifique o status do ILM do índice de suporte em seguida com o seguinte comando:

• É normal ver que o índice está em alta, pois foi criado muito recentemente (revise a linha 8 ou 10).

Execute o seguinte para fazer a transição do índice de apoio do nível ativo para o próximo nível apropriado, após a fase ativa da política de ILM para esse fluxo de dados. Os valores específicos para phase, actione name no current_step abaixo podem ser referenciados a partir das linhas 11, 13 e 15, respectivamente, na captura de tela fornecida acima.

O valor next_step indica a fase ou camada de dados ILM subsequente para a qual o índice irá transitar.

Por exemplo:

• Não é necessário, mas como medida de segurança, você pode executar o comando _ilm/explain novamente para garantir que o índice de apoio tenha passado para a próxima fase e não esteja mais ativo.

Uma vez que as seguintes condições forem atendidas, você pode deletar com segurança o índice de suporte original que apresentava conflitos de mapeamento:

1. Um novo índice de suporte foi criado com sucesso.
2. Os documentos foram movidos para o novo índice e as contagens de documentos coincidem.
3. Os mapeamentos foram corrigidos (tanto específicos do fluxo de dados quanto do ECS).
4. O fluxo de dados incorpora o novo índice de apoio.
5. A política de ILM foi aplicada e moveu o índice para fora da fase quente.

Importante: alternativamente, antes de excluir o índice original, você pode verificar a página Visualizações de Dados. Selecione logs-* e verifique se o índice de respaldo reindexado (que termina em -1) agora aparece na seção long. O índice original de suporte ainda deve estar presente sob keyword. Se o índice de respaldo reindexado não estiver na seção long, volte e revise os passos anteriores e faça as correções necessárias.

Por exemplo:

Depois de resolver os conflitos, retorne à página Data Views e selecione logs-*. Se o conflito estiver relacionado apenas a log.offset, você não verá mais nenhum conflito listado. Se houver outros conflitos, o índice de suporte original não deverá mais aparecer na lista de conflitos; em vez disso, o novo índice de suporte deverá ser listado na seção long.

Você também pode verificar no Discover que o campo log.offset agora exibe os ícones apropriados.

Continue esse processo, repetindo os passos acima para cada índice que tenha conflito de mapeamento até que todos sejam resolvidos com sucesso.

Referências:

• Referência de campo do ECS
• Reindexar documentos

Conclusão

Ao seguir os passos deste blog, você resolverá conflitos de mapeamento e garantirá que todos os novos dados sejam mapeados corretamente. Isso é alcançado ao vincular os modelos de componentes necessários à sua fonte de dados. Esse fluxo de trabalho não apenas resolve os problemas imediatos, mas também estabelece um processo seguro e repetível para gerenciar alterações de esquema conforme seus dados e requisitos evoluem.