O Elasticsearch estava rejeitando métricas de chegada tardia. Essas rejeições fizeram o pipeline ficar atrasado, resultando em dados mais tardios, o que desencadeou ainda mais rejeições. Com o tempo, o pipeline parou completamente.

Tivemos que restaurar a partir do snapshot, reindexar os dados e redesenhar o pipeline de ingestão para recuperar.

A causa raiz não era a gestão de ciclo de vida de índices (ILM) em si. Tratava-se de fluxos de dados de séries temporais (TSDS) e como eles aplicam índices de apoio com limite temporal.

O TSDS pode reduzir os requisitos de armazenamento para métricas em 40–70%, mas as mudanças na arquitetura que tornam o TSDS eficiente também alteram a forma como os índices se comportam ao longo do tempo. Essas mudanças são importantes ao projetar políticas de ILM ou quando seus pipelines de ingestão podem produzir dados tardios.

TL;DR

Ao usar o TSDS:

• Índices de suporte aceitam apenas documentos dentro de uma janela de tempo específica.

• Se dados tardios chegarem após um índice se tornar frio ou congelado, o Elasticsearch rejeitará esses documentos ou os encaminhará para o armazenamento de falhas, caso esteja configurado.

Regra de design:

O que é um fluxo de dados de séries temporais?

Um fluxo de dados de série temporal (TSDS) é um fluxo de dados especializado otimizado para dados métricos. Os dados são roteados de modo que documentos relacionados fiquem localizados dentro dos mesmos fragmentos, otimizando-os para consulta e recuperação. Como o Elasticsearch faz isso:

Cada documento contém:

• Um registro de data e hora.

• Campos dimensionais que identificam a série de tempo.

• Campos métricos representando valores medidos.

Alguns exemplos:

• Uso da CPU por host.

• Solicitar latência por serviço.

• Leituras de temperatura por sensor.

As dimensões identificam o que queremos medir, enquanto as métricas representam valores que mudam com o tempo.

Dimensões

Dimensões descrevem a entidade medida.

Exemplos:

Definimos eles em mapeamentos com:

Métricas

Métricas representam valores numéricos e são definidas usando:

Tipos comuns de métricas:

• Indicador: Valores que sobem e descem.

• Contador: valores que aumentam até serem reiniciados.

O Elastic Agent coleta principalmente métricas e dados de log. Mesmo que você não tenha habilitado manualmente nenhum índice TSDS, ainda pode tê-los no seu cluster.

O campo _tsid

O Elasticsearch gera internamente um valor _tsid a partir dos campos de dimensão. Isso permite que documentos com dimensões idênticas sejam roteados para o mesmo shard, melhorando:

• Compressão.

• Local da consulta.

• Desempenho de agregações.

A principal diferença: índices de apoio com prazo definido

Os fluxos de dados tradicionais sempre gravam no índice de suporte mais recente, chamado índice de gravação, mas o TSDS se comporta de maneira diferente.

Cada índice de apoio TSDS tem uma janela de tempo definida e aceita apenas documentos com @timestamp valores que se encaixam nessa janela:

Quando um documento é indexado, o Elasticsearch encaminha o documento para o índice de suporte responsável por aquele timestamp, o que significa que, ao contrário dos índices tradicionais, um TSDS pode gravar em vários índices de suporte simultaneamente.

Por exemplo:

• Dados em tempo real → índice mais recente.

• Dados tardios → índice anterior cobrindo esse intervalo de tempo.

Projetando para dados tardios

Os pipelines de ingestão reais raramente entregam métricas perfeitamente no prazo. As métricas podem ser atrasadas por interrupções de rede, acúmulos no caminho, ingestão em lote e perda de dispositivos de borda, que se reconectam e começam a recuperar o atraso.

Índices tradicionais absorvem silenciosamente esses atrasos. O TSDS não.

Se o carimbo de data/hora de um documento estiver fora da faixa de índices de apoio graváveis, o Elasticsearch o rejeitará, o que significa que sua política de ILM deve considerar os dados tardios.

A restrição crítica

Os índices de suporte precisam permanecer com permissão de escrita por tempo suficiente para receber dados com atraso.

Em termos práticos:

Como o ILM mede o tempo de existência a partir do rollover, a regra operacional passa a ser:

Por exemplo, se as métricas podem chegar até seis horas atrasadas, os índices devem permanecer graváveis pelo menos seis horas após o rollover.

Desconsiderar essa restrição foi exatamente o que causou a falha de ingestão descrita anteriormente. Os dados tardios eram direcionados para um índice anterior, que já estava na camada cold e, portanto, era bloqueado para escrita.

Tratamento de documentos rejeitados

Quando o TSDS rejeita um documento, o Elasticsearch retorna um erro, indicando que o carimbo de data e hora não está dentro da faixa de índices graváveis. Como seu pipeline de ingestão lida com esse erro determina se você perde dados ou trava a ingestão de dados.

O principal mecanismo para lidar com documentos rejeitados é o armazenamento de falhas.

Repositório de falhas (recomendado no Elasticsearch 9.1+)

O Elasticsearch 9.1 introduziu o armazenamento de falhas, que captura automaticamente documentos rejeitados. Em vez de retornar erros aos clientes, o Elasticsearch grava documentos rejeitados em um índice dedicado de falhas dentro do fluxo de dados.

Você pode inspecionar falhas usando:

O uso do armazenamento de falhas impede que os pipelines de ingestão travem devido a erros de rejeição, enquanto preserva os dados com falha para análise ou reindexação.

Monitoramento de questões de rejeição

Os problemas de chegada tardia geralmente aparecem primeiro como anomalias de ingestão. Você pode notá-los primeiro como:

• Quedas repentinas na taxa de indexação.

• Picos nos documentos rejeitados.

• Um número crescente de entradas de lojas que falham.

• Diferenças de incompatibilidade entre entradas e saídas do pipeline contagem.

Alertas nesses sinais permitem que os operadores detectem problemas antes que os pipelines parem. Fluxos de trabalho, trabalhos de Machine Learning e outros mecanismos podem ser usados para automatizar a detecção e notificação.

Lista de verificação de migração para TSDS + ILM

Se você estiver migrando um cluster de métricas para o TSDS, introduzindo a hierarquização do ILM ou atualizando para uma versão do Elasticsearch em que as métricas são TSDS por padrão, revise esses itens primeiro.

1. Medir a latência de ingestão

Antes de mudar as políticas de ILM, determine:

• Atraso normal na ingestão de dados.

• Pior caso de atraso durante os incidentes.

• Atrasos causados por pipelines em lote.

O projeto do seu ILM deve acomodar o máximo de atraso realista.

2. Verificar as janelas de tempo do índice

Inspecione seus índices de respaldo de TSDS:

Analise:

• time_series.start_time

• time_series.end_time

Esses limites determinam quais índices podem aceitar documentos. Entender essas janelas pode ajudar a determinar o quanto os dados podem estar atrasados antes de serem rejeitados.

3. Dimensione o nível hot para chegadas tardias

Garanta que os índices backing permaneçam graváveis por tempo suficiente para os dados tardios.

Regra operacional:

• warm_min_age > rollover_max_age + maximum_expected_lateness

Lembre-se, os índices devem permanecer graváveis por pelo menos seis horas se as métricas chegarem com seis horas de atraso.

4. Decida o que fazer com documentos rejeitados

Escolha uma estratégia antes de ativar o TSDS:

• Armazenamento de falhas (recomendado no Elasticsearch 9.1+).

• Fila de dead letter do Logstash.

• Índice de contingência para chegadas tardias.

• Aceitar a perda limitada de dados.

5. Monitorar a saúde da ingestão

Adicionar alertas para:

• A taxa de indexação cai.

• Documentos rejeitados.

• Crescimento do armazenamento de falhas.

• Desajustes de entrada/saída do pipeline.

Problemas de dados tardios geralmente aparecem primeiro como anomalias de ingestão.

Resumo

Fluxos de dados de séries temporais oferecem grandes melhorias de armazenamento e desempenho para cargas de trabalho de métricas, mas introduzem uma mudança arquitetônica importante: os índices de suporte têm limite temporal, o que afeta o comportamento do ILM.

Ao usar o TSDS:

• Os índices devem permanecer graváveis tempo suficiente para aceitar dados tardios.

• Os pipelines de ingestão devem lidar com documentos rejeitados com segurança.

A regra fundamental a lembrar é:

Se você projetar políticas de ILM em torno dessa restrição, o TSDS funcionará extremamente bem para cargas de trabalho de métricas.

Se ignorar isso, seu pipeline de ingestão pode descobrir esses limites de tempo da pior forma.

Tradicionalmente, o gerenciamento de rastreadores era um processo manual e propenso a erros. Isso envolvia editar configurações diretamente na interface do usuário e ter dificuldades com a clonagem de configurações de rastreamento, reversão, controle de versão e muito mais. Tratar as configurações do rastreador como código resolve isso, proporcionando os mesmos benefícios que esperamos no desenvolvimento de software: repetibilidade, rastreabilidade e automação.

Esse fluxo de trabalho facilita a integração do Open Web Crawler ao seu pipeline de CI/CD para reversões, backups e migrações — tarefas que eram muito mais complicadas com versões anteriores do Elastic Crawler, como o Elastic Web Crawler ou o App Search Crawler.

Neste artigo, vamos aprender como:

• Gerencie nossas configurações de rastreamento usando o GitHub.

• Ter um ambiente local para testar pipelines antes da implantação.

• Criar um ambiente de produção para executar o rastreador web com novas configurações sempre que enviarmos alterações para nossa branch principal.

Você pode encontrar o repositório do projeto aqui. No momento em que escrevo, estou usando o Elasticsearch 9.1.3 e o Open Web Crawler 0.4.2.

Pré-requisitos

• Docker Desktop

• instância do Elasticsearch

• Máquina virtual com acesso SSH (por exemplo, AWS EC2) e Docker instalado.

Etapas

1. Estrutura de pastas

2. Configuração do rastreador

3. Arquivo Docker-compose (ambiente local)

4. Ações do GitHub

5. Testando localmente

6. Implantação em produção

7. Realizar alterações e redistribuir

Estrutura de pastas

Para este projeto, teremos a seguinte estrutura de arquivos:

Configuração do rastreador

Em crawler-config.yml, colocaremos o seguinte:

Este script irá extrair dados de https://web-scraping.dev/products, um site fictício para produtos. Iremos rastrear apenas as três primeiras páginas de produtos. A configuração max_crawl_depth impedirá que o rastreador descubra mais páginas do que as definidas como seed_urls , não abrindo os links dentro delas.

Elasticsearch host e api_key serão preenchidos dinamicamente dependendo do ambiente em que estamos executando o script.

Arquivo Docker-compose (ambiente local)

Para o ambiente local docker-compose.yml, implantaremos o rastreador e um único cluster Elasticsearch + Kibana, para que possamos visualizar facilmente os resultados do rastreamento antes da implantação em produção.

Observe como o rastreador aguarda até que o Elasticsearch esteja pronto para ser executado.

Ações do GitHub

Agora precisamos criar uma ação do GitHub que copie as novas configurações e execute o rastreador em nossa máquina virtual a cada push para o repositório principal. Isso garante que sempre tenhamos a configuração mais recente implantada, sem precisar entrar manualmente na máquina virtual para atualizar arquivos e executar o rastreador. Vamos usar o AWS EC2 como provedor de máquinas virtuais.

O primeiro passo é adicionar o host (VM_HOST), o usuário da máquina (VM_USER), a chave SSH RSA (VM_KEY), o host do Elasticsearch (ES_HOST) e a chave da API do Elasticsearch (ES_API_KEY) aos segredos da ação do GitHub:

Dessa forma, a ação poderá acessar nosso servidor para copiar os novos arquivos e executar a indexação.

Agora, vamos criar nosso arquivo .github/workflows/deploy.yml :

Essa ação executará os seguintes passos sempre que enviarmos alterações para o arquivo de configuração do rastreador:

1. Preencha o arquivo de configuração YAML com o host e a chave da API do Elasticsearch.

2. Copie a pasta de configuração para a nossa máquina virtual.

3. Conecte-se à nossa VM via SSH.

4. Execute o rastreamento com a configuração que acabamos de copiar do repositório.

Testando localmente

Para testar nosso rastreador localmente, criamos um script bash que popula o host do Elasticsearch com a versão local do Docker e inicia uma busca. Você pode executar ./local.sh para executá-lo.

Vamos verificar as Ferramentas de Desenvolvedor do Kibana para confirmar se o campo web-crawler-index foi preenchido corretamente:

Implantação em produção

Agora estamos prontos para enviar a alteração para a branch principal, o que implantará o crawler em sua máquina virtual e começará a enviar logs para sua instância do Elasticsearch Serverless.

Isso acionará a ação do GitHub, que executará o script de implantação na máquina virtual e iniciará a indexação.

Você pode confirmar se a ação foi executada acessando o repositório do GitHub e visitando a aba “Ações”:

Realizar alterações e redistribuir

Algo que você pode ter notado é que o price de cada produto faz parte do corpo do documento. O ideal seria armazenar o preço em um campo separado para que pudéssemos aplicar filtros a ele.

Vamos adicionar essa alteração ao arquivo crawler.yml para usar regras de extração para extrair o preço da classe CSS product-price :

Também vemos que o preço inclui um sinal de dólar ($), que devemos remover se quisermos executar consultas de intervalo. Podemos usar um pipeline de ingestão para isso. Observe que estamos fazendo referência a ele em nosso novo arquivo de configuração do rastreador acima:

Podemos executar esse comando em nosso cluster Elasticsearch de produção. Para o desenvolvimento, como é efêmero, podemos fazer com que a criação do pipeline faça parte do arquivo docker-compose.yml adicionando o seguinte serviço. Observe que também adicionamos um depends_on ao serviço de rastreamento para que ele seja iniciado após a criação bem-sucedida do pipeline.

Agora vamos executar `./local.sh` para ver a alteração localmente:

Ótimo! Agora vamos impulsionar a mudança:

Para confirmar se tudo funciona corretamente, você pode verificar seu Kibana de produção, que deverá refletir as alterações e mostrar o preço como um novo campo sem o símbolo de dólar.

Conclusão

O Elastic Open Web Crawler permite que você gerencie seu crawler como código, o que significa que você pode automatizar todo o pipeline — do desenvolvimento à implantação — e adicionar ambientes locais efêmeros e testes com os dados rastreados programaticamente, para citar alguns exemplos.

Você está convidado a clonar o repositório oficial e começar a indexar seus próprios dados usando este fluxo de trabalho. Você também pode ler este artigo para aprender como executar uma pesquisa semântica em índices produzidos pelo rastreador.

1. Utilizando a API _mapping para recuperar informações de campo

2. Utilizando a API _search para exibir valores de campo

3. Exibição de subcampos

4. _source sintética

5. Campos de tempo de execução

1. Utilizando a API _mapping para recuperar informações de campo

A API _mapping permite recuperar a definição de mapeamento para um índice ou vários índices. Isso inclui informações sobre os campos, seus tipos de dados e outras propriedades. Para recuperar o mapeamento de um índice específico, utilize a seguinte solicitação:

Por exemplo, se você tiver um índice chamado my_index, poderá recuperar seu mapeamento com a seguinte solicitação:

A resposta incluirá a definição de mapeamento para o índice, que contém informações sobre os campos e suas propriedades.

Também é possível recuperar o mapeamento de um campo específico. Isso pode ser útil se o seu mapeamento for muito extenso e você quiser se concentrar apenas em um campo específico. Para obter o mapeamento de um campo específico, utilize a seguinte solicitação:

Você também pode recuperar os mapeamentos de vários campos separando seus nomes por vírgulas, como na seguinte solicitação:

2. Usando a API _search para exibir valores de campo

Para exibir os valores dos campos em um índice do Elasticsearch, você pode usar a API _search . A API _search oferece várias maneiras de controlar quais campos são retornados; as duas principais são:

1. _sourceO campo _source contém o corpo original do documento JSON exatamente como foi indexado, incluindo quaisquer alterações feitas pelos pipelines de ingestão ou etapas de pré-processamento. Para exibir campos específicos do documento de origem, implemente a filtragem de origem, como veremos a seguir.

2. fieldsO parâmetro fields permite recuperar campos específicos dos seus documentos ao realizar uma pesquisa, com base no mapeamento do índice. Ao contrário de _source, fields também pode retornar valores de campos armazenados, valores de documentos ou campos de tempo de execução sem fazer referência a _source, embora para campos padrão sem valores de documentos ou configurações armazenadas, ele recorra a _source. Isso pode trazer muitos benefícios, como melhoria de desempenho e outros, como veremos a seguir.

Usando o campo _source

Por padrão, a API _search retorna o campo _source , que contém o documento JSON original que foi indexado. Para exibir campos específicos, você pode adicionar filtros no parâmetro _source da solicitação de pesquisa; isso é chamado de filtragem de origem.

Aqui está um exemplo de uma solicitação de pesquisa que retorna os valores dos campos title e author para documentos no índice my_index :

Neste exemplo, o parâmetro _source especifica os campos a serem retornados.

Se você precisar de ainda mais controle, pode usar as propriedades includes e excludes do objeto _source . Por exemplo, a consulta abaixo retorna o campo de nível superior title e todos os subcampos de author exceto author.description.

Neste exemplo, usamos o padrão author.* para recuperar todos os subcampos diretos do objeto author . Então excluímos explicitamente author.description para que apenas os outros campos de autor sejam retornados. Note que isso não traz nenhuma melhoria de desempenho, já que ainda precisa carregar e analisar o JSON de origem, mas pode reduzir o tamanho da resposta enviada pela rede.

Usando o parâmetro de campos

Você pode usar o parâmetro fields para filtrar os campos retornados na resposta da pesquisa. O uso de fields em vez de _source oferece diversas vantagens, incluindo:

• Desempenho aprimorado: fields pode retornar valores diretamente de campos armazenados ou valores de documentos sem ter que carregar o _source completo, tornando o tamanho da carga útil da resposta menor.

• Saída formatada: Para campos padrão, fields pode recorrer a _source para obter os valores, mas ele analisa o mapeamento do índice para formatar corretamente a saída, como datas formatadas, tornando-as consistentes com o que é usado para agregações e classificação.

• Acesso a campos de tempo de execução: fields pode retornar campos de tempo de execução, que não existem no _source original.

• Você pode encontrar mais benefícios aqui.

Por exemplo, para retornar apenas os campos title e author no índice my_index , você pode usar a seguinte solicitação de pesquisa:

Na consulta acima, definimos o campo _source como falso para não retornarmos o documento de origem. Isso pode minimizar drasticamente o tamanho da carga útil da resposta, mas lembre-se de que isso só funciona porque os campos title e author são do tipo de campo keyword , que têm doc_values habilitado por padrão. Se o campo não tiver doc_values habilitado e _source estiver definido como falso, o Elasticsearch não terá como recuperá-los e eles serão ignorados na resposta.

É importante notar que a resposta fields sempre retorna uma matriz de valores para cada campo, mesmo que haja apenas um único valor. Isso ocorre porque o Elasticsearch não possui um tipo de array dedicado, e qualquer campo pode ter vários valores. Para obter mais informações sobre arrays no Elasticsearch, clique aqui.

Outras formas de recuperar campos

Embora a recuperação de campos usando _source ou fields sejam os métodos recomendados, existem outros métodos disponíveis para casos de uso específicos, como:

Campos de valor do documento: Se você quiser evitar _source completamente, você pode pesquisar usando o parâmetro docvalue_fields . Os valores do documento armazenam os mesmos valores de campo que _source , mas em uma estrutura de dados em disco, otimizada para classificação e agregações.

Como é separado dos valores armazenados com _source, você pode solicitar campos específicos sem carregar todo o _source. Isso é útil se você estiver consultando documentos grandes, mas precisar apenas de alguns campos pequenos que suportem valores do tipo "doc". Outro caso de uso para usar docvalue_fields é quando você deseja usar formatação personalizada nos campos date e numeric , como veremos no exemplo abaixo.

Observe que isso só funciona para campos que você habilita doc_values ou para tipos de campo que o têm habilitado por padrão, como keyword, date, tipos numéricos e boolean, não para text ou annotated_text.

Neste exemplo, usamos o parâmetro docvalue_fields para recuperar os campos title, author e published sem carregar o documento _source completo:

Quando esta consulta é executada, o Elasticsearch obtém os valores diretamente de seu armazenamento colunar em disco, em vez de referenciar o _source para cada documento. O campo published é retornado com o formato epoch_millis em vez do formato padrão, graças ao parâmetro format fornecido na consulta.

Campos armazenados: Se você marcou explicitamente campos específicos como armazenados no mapeamento, você pode usar o parâmetro stored_fields para filtrar esses campos. Isso é útil se você deseja respostas resumidas apenas com esses campos específicos ou para campos que você armazenou deliberadamente para recuperação posterior. É armazenado separadamente de _source, portanto, este método também é útil para evitar a necessidade de carregar _source.

É importante notar que esta opção está desativada por padrão e geralmente não é recomendada. Em vez disso, utilize a filtragem de origem para retornar determinados subconjuntos do documento de origem original.

Na consulta de exemplo abaixo, usamos o parâmetro stored_fields para recuperar o campo summary , que tem a configuração de mapeamento de índice de ”store”: true.

Quando esta consulta é executada, o Elasticsearch verifica se este campo foi marcado com ”store”: true, se não o encontrar, irá ignorar o campo completamente.

3. Exibição de subcampos

Se o seu índice contiver subcampos, você pode usar a notação de ponto para especificar o caminho do campo no parâmetro fields . Note que os subcampos são diferentes do tipo de campo aninhado. Por exemplo, se você tiver um subcampo chamado address.city, poderá incluí-lo na resposta da pesquisa desta forma:

Neste exemplo, a resposta da pesquisa incluirá os valores dos campos title, author e address.city .

4. Fonte sintética

Se você quiser manter a funcionalidade de usar _source , mas também economizar espaço em disco, você tem a opção de usar _source sintético em seu mapeamento de índice. _source sintético é um recurso que permite ao Elasticsearch reconstruir o _source a partir de dados existentes, como campos armazenados e valores de documentos, mesmo quando _source está desativado. Isso permite economizar bastante espaço de armazenamento, ao custo de velocidades ligeiramente menores no momento da consulta, já que a reconstrução ocorre em tempo real. Ative este recurso usando os valores abaixo nas configurações do seu índice:

Algumas vantagens de usar _source sintético incluem: exibição do documento completo ao usar a API _search , filtragem de origem e compatibilidade com outros recursos e ferramentas como o Kibana que esperam que _source esteja disponível, tudo isso evitando a necessidade de armazenar o documento _source completo.

5. Campos de tempo de execução

Os campos de tempo de execução permitem definir campos com script no momento da consulta ou no mapeamento do índice, dentro de um bloco de tempo de execução. Esses campos nunca são indexados, portanto, adicionar um campo de tempo de execução não aumenta o tamanho do índice, mas nunca aparecerá em _source. Os campos de tempo de execução definidos no mapeamento são persistentes e estão disponíveis para todas as consultas, enquanto os campos de tempo de execução definidos no momento da consulta são temporários e estão disponíveis apenas nessa solicitação de pesquisa.

A principal vantagem de usar campos em tempo de execução é a capacidade de adicionar campos aos documentos depois de já os ter importado, simplificando as decisões de mapeamento. Os campos de tempo de execução também são ótimos para enriquecer seus documentos com valores que não existem no documento original, mas são gerados por meio de um script, como formatar uma string ou calcular uma pontuação.

Vale ressaltar também que os campos de tempo de execução podem prejudicar o desempenho, pois será necessário executar um script para cada documento no conjunto de resultados. Para recuperar um campo de tempo de execução, você também pode usar o parâmetro fields na API _search .

Conclusão

A exibição de campos de um índice Elasticsearch pode variar desde a simples recuperação de valores usando o mapeamento de índice ou o _source, até métodos mais avançados usando fields, docvalue_fields ou campos de tempo de execução para maior controle e eficiência. Compreender as vantagens e desvantagens de diferentes métodos é fundamental para otimizar suas experiências de busca. Seja para otimizar payloads, enriquecer documentos ou usar dados sintéticos _source para economizar armazenamento, o Elasticsearch oferece diversas ferramentas e recursos para encontrar os dados que você precisa, da maneira que você precisa. Essas técnicas podem ajudá-lo a entender a estrutura de seus dados, identificar campos específicos e solucionar problemas.

O Logstash inclui diversos filtros integrados para tarefas comuns, como analisar, enriquecer e modificar dados. Mas, às vezes, você encontrará cenários que exigem lógica personalizada que vai além do que esses filtros padrão podem fornecer. É aí que entra o plugin de filtro Ruby .

O plugin de filtro Ruby permite executar código Ruby personalizado diretamente no seu pipeline Logstash. Quando os filtros padrão não são suficientes, o filtro Ruby permite lidar com transformações de dados complexas, implementar lógica de negócios personalizada ou integrar-se a sistemas externos.

Neste blog, vamos explorar como usar filtros em Ruby, desde o uso básico até o avançado.

Quando você deve usar o filtro Ruby?

Como arquiteto consultor da Elastic, vejo frequentemente clientes usando o Logstash para o pipeline de processamento de dados, embora atualmente ele não seja um mecanismo de processamento de dados de última geração. Eles frequentemente enfrentam dificuldades com as limitações dos filtros padrão quando se trata de manipulação complexa de dados ou lógica personalizada. Nesses casos, o filtro Ruby pode ajudar a superar esses desafios.

O filtro Ruby é útil quando os filtros padrão do Logstash não atendem às suas necessidades específicas. Aqui estão alguns casos de uso comuns:

• Manipulação de dados aninhados em profundidade: Modifique estruturas JSON complexas, arrays dentro de arrays ou reestruture dados dinamicamente com base no conteúdo.

• Processamento avançado de strings: Analise e extraia dados estruturados de textos não estruturados.

• Implementação de lógica de negócios complexa: Crie transformações personalizadas que exigem lógica condicional, loops ou cálculos complexos.

Uso básico

Vamos começar com um exemplo simples para entender como funciona o filtro Ruby.

Configurando o filtro Ruby

Ao criar um pipeline Logstash, você deve colocar o arquivo de configuração no diretório /etc/logstash/conf.d . Alternativamente, você pode usar a opção -f para especificar o caminho para o arquivo de configuração ao iniciar o Logstash manualmente, para que você possa experimentar seus pipelines facilmente.

O arquivo de configuração deve ter a extensão .conf .

Para usar o filtro Ruby, defina um filtro ruby na seção de filtro do seu arquivo de configuração do pipeline Logstash (*.conf). Eis um exemplo básico:

Este filtro Ruby embutido define uma instância de filtro Ruby dentro da sua configuração do Logstash. O parâmetro code fornece o script Ruby embutido que o Logstash executará para cada evento processado por este filtro. Dentro desse script, há uma variável event disponível que representa o próprio evento. O objeto de evento contém os dados originais enviados ao Logstash e quaisquer campos adicionais criados durante os estágios de filtragem do Logstash. Você pode acessar esses campos por meio da API de Eventos do Logstash, como event.get() e event.set(). Neste exemplo de código, event.set('new_field', 'Hello from Ruby!') definiu um novo campo chamado new_field com o valor da string Hello from Ruby!. Você pode adicionar qualquer outro código neste bloco code conforme necessário.

Note que este objeto event não é um objeto hash comum do Ruby, embora funcione como um contêiner de dados do tipo chave-valor. Consulte esta documentação oficial para saber mais sobre a API de Eventos.

Externalizar script Ruby

Para transformações simples, o código Ruby embutido é conveniente. Porém, para lógica complexa ou funções reutilizáveis, recomenda-se mover o código para um script Ruby externo. Isso melhora a capacidade de manutenção e mantém a configuração do seu pipeline Logstash organizada.

Primeiro, crie um script Ruby e salve-o como my_ruby_script.rb. O script deve definir um método filter que processa o evento. Ela recebe um objeto de evento como argumento, que representa o evento atual que está sendo processado. O método filter precisa retornar uma matriz de eventos para emitir. Para descartar o evento, retorne um array vazio.

Por exemplo, o seguinte script lê o campo message , calcula seu comprimento e armazena o resultado em um novo campo chamado message_length.

Em seguida, defina a configuração do filtro Ruby para referenciar o script usando a opção path . Isso instrui o Logstash a carregar e executar o script externo. Ao usar scripts externos, certifique-se de que o arquivo existe e possui as permissões corretas.

Agora, cada evento é passado para o método filter em my_ruby_script.rb e é processado por ele.

Essa abordagem ajuda você a gerenciar lógicas complexas com mais eficiência, facilitando o teste, a depuração e a reutilização do seu código Ruby.

Uso avançado

Nesta seção, exploraremos alguns exemplos avançados de uso do filtro Ruby no Logstash. Estes exemplos demonstrarão como realizar transformações de dados, enriquecer eventos e implementar lógica personalizada usando Ruby.

Manipulando estruturas de dados aninhadas

Um evento do Logstash é a estrutura de dados principal que o Logstash processa. Pode conter diversos campos, incluindo estruturas de dados aninhadas, como arrays e hashes. O filtro Ruby permite manipular essas estruturas aninhadas com facilidade.

O filtro Ruby consegue lidar com estruturas de dados aninhadas, como hashes e arrays, permitindo que você modifique ou adicione campos dentro dessas estruturas. Isso é útil ao lidar com formatos de dados complexos como JSON.

Este exemplo inclui um objeto JSON aninhado nos dados de entrada. O filtro Ruby modifica os dados aninhados adicionando um novo par chave-valor. Esse tipo de manipulação de dados aninhados não é possível com os filtros padrão do Logstash, o que torna o filtro Ruby uma opção prática para estruturas de dados complexas.

Dividir um único evento em vários eventos.

Os filtros Ruby também podem ser usados para dividir um único evento em vários eventos. Isso é útil quando você tem um único evento contendo uma matriz de itens e deseja criar eventos separados para cada item.

Note que nem o pipeline de ingestão do Elasticsearch nem os processadores do Beats/Elastic Agent suportam a divisão de eventos. Este é um dos casos de uso mais fortes para o Logstash.

Com filtro dividido

Você pode usar o filtro split para dividir um evento em vários eventos com base em um campo especificado. No entanto, se precisar realizar transformações ou lógicas adicionais durante a divisão, você pode usar o filtro Ruby em combinação com o filtro de divisão.

No exemplo a seguir, temos um feed RSS como uma única linha de texto XML. Contém múltiplos elementos <item> . O filtro Ruby é usado para extrair os elementos <item> do XML e armazená-los em um novo campo chamado items. O filtro de divisão é então usado para dividir o evento em vários eventos com base no campo items .

Isso resultará no seguinte:

Como você deve ter percebido, o filtro ruby não é essencial neste caso. O filtro split pode ser usado para dividir o evento em vários eventos com base no campo items e o filtro mutate pode ser usado para remover campos desnecessários. No entanto, se você precisar realizar transformações ou lógicas adicionais durante a divisão, poderá usar o filtro Ruby.

Use script Ruby embutido

Você também pode usar um script Ruby embutido para dividir um único evento em vários eventos usando o método event.clone e o new_event_block variable, como new_event_block.call(new_event). Isso permite criar novos eventos com base no evento original, preservando seus dados.

Aqui está um exemplo de como usar o filtro Ruby para dividir um único evento em vários eventos. A entrada e a saída são as mesmas do exemplo anterior.

Utilizar script Ruby externo

Você também pode usar um script Ruby externo para dividir um único evento em vários eventos.

Arquivo de configuração:

O script Ruby precisa ser externalizado como split_event.rb:

Lembre-se, o método filter deve retornar uma matriz de eventos. Você pode retornar vários eventos clonando um objeto de evento recebido e adicionando-os à matriz, ou pode retornar um único evento como uma matriz com um único elemento.

Isso permite dividir um único evento em vários eventos.

Executar comandos externos e analisar seus resultados.

O plugin Logstash exec input permite executar comandos externos, e a saída desses comandos será um evento do Logstash. O resultado do comando será armazenado no campo message do evento.

Normalmente, a saída dos comandos do sistema é legível para humanos, mas não está estruturada em JSON ou outros formatos que o Logstash possa analisar facilmente. Para lidar com isso, você pode usar o filtro Ruby para analisar a saída e extrair as informações dela.

Aqui está um exemplo de uso do plugin de entrada exec para executar o comando ps -ef , que lista todos os processos em execução em um sistema do tipo Unix. A saída será analisada pelo filtro Ruby para extrair informações relevantes sobre cada processo.

Este exemplo usa o plugin de entrada exec para executar o comando ps -ef a cada 60 segundos. O filtro Ruby processa a saída, extraindo campos relevantes como UID, PID, PPID, uso da CPU (C), hora de início (STIME), TTY, tempo total da CPU (TIME) e o comando (CMD) executado. Funciona bem no meu ambiente macOS, mas você pode precisar ajustar os padrões regex para corresponder ao formato de saída do comando ps -ef no seu sistema.

Utilize bibliotecas integradas

O plugin de filtro Ruby permite usar bibliotecas Ruby integradas, o que pode ser muito útil para diversas tarefas. Por exemplo, você pode usar a biblioteca json para analisar strings JSON ou a biblioteca date para manipular datas.

Aqui está um exemplo de como usar a biblioteca json para analisar uma string JSON armazenada em um campo:

Para evitar exigir a biblioteca sempre, você deve externalizar seu código Ruby para que possa usar a instrução require no início do seu script de filtro Ruby. Isso carregará a biblioteca uma única vez e a tornará disponível para uso em seu script.

Para verificar quais bibliotecas estão disponíveis em seu ambiente, você pode listar as bibliotecas integradas executando o seguinte código no filtro Ruby:

Observação: as bibliotecas integradas não são oficialmente suportadas pelo Logstash e seu comportamento pode mudar ou elas podem não estar disponíveis em versões futuras. Use-os por sua conta e risco.

Conclusão

O filtro Logstash Ruby permite personalizar e ampliar as funcionalidades dos seus pipelines Logstash. Neste post, abordamos os conceitos básicos do uso do filtro Ruby e fornecemos exemplos de uso avançado.

Ao utilizar o filtro Ruby, você pode lidar com tarefas complexas de processamento de dados que exigem lógica personalizada ou manipulação avançada. Seja trabalhando com estruturas de dados aninhadas, dividindo eventos ou analisando e convertendo texto complexo/não estruturado em JSON estruturado, o filtro Ruby oferece a flexibilidade necessária para atender às suas necessidades específicas.

Esperamos que este guia tenha lhe fornecido o conhecimento e a inspiração necessários para explorar todo o potencial do filtro Logstash Ruby. Boa programação!

1. Utilizando a API_mappingpara recuperar informações de campo

2. Utilizando a API_searchpara exibir valores de campo

3. Filtrar campos usando o parâmetrofields

4. Exibindo campos aninhados

1. Utilizando a API _mapping para recuperar informações de campo

A API _mapping permite recuperar a definição de mapeamento para um índice ou vários índices. Isso inclui informações sobre os campos, seus tipos de dados e outras propriedades. Para recuperar o mapeamento de um índice específico, utilize a seguinte solicitação:

Por exemplo, se você tiver um índice chamado my_index, poderá recuperar seu mapeamento com a seguinte solicitação:

A resposta incluirá a definição de mapeamento para o índice, que contém informações sobre os campos e suas propriedades.

Também é possível recuperar o mapeamento de um campo específico. Isso pode ser útil se o seu mapeamento for muito extenso e você quiser se concentrar apenas em um campo específico. Para obter o mapeamento de um campo específico, utilize a seguinte solicitação:

Você também pode recuperar os mapeamentos de vários campos separando seus nomes com vírgulas, como na seguinte solicitação:

2. Usando a API _search para exibir valores de campo

Para exibir os valores dos campos em um índice do Elasticsearch, você pode usar a API _search . Por padrão, a API _search retorna o campo _source , que contém o documento JSON original que foi indexado. Para exibir apenas campos específicos, você pode usar o parâmetro _source na solicitação de pesquisa.

Aqui está um exemplo de uma solicitação de pesquisa que retorna os valores dos campos title e author para documentos no índice my_index :

Neste exemplo, o parâmetro _source especifica os campos a serem retornados.

3. Filtrar campos usando o parâmetro fields

Você também pode usar o parâmetro fields para filtrar os campos retornados na resposta da pesquisa. Isso pode ser útil se você precisar apenas de campos específicos e quiser reduzir o tamanho da resposta. O parâmetro fields aceita uma matriz de nomes de campos ou padrões curinga.

Por exemplo, para retornar apenas os campos title e author para documentos no índice my_index , você pode usar a seguinte solicitação de pesquisa:

Note que o parâmetro _source está definido como falso para não retornar o documento de origem.

Para retornar todos os campos com o tipo de dados text , você pode usar um padrão curinga como este:

4. Exibição de campos aninhados

Se o seu índice contiver campos aninhados, você pode usar a notação de ponto para especificar o caminho do campo aninhado no parâmetro fields . Por exemplo, se você tiver um campo aninhado chamado address.city, poderá incluí-lo na resposta da pesquisa desta forma:

Neste exemplo, a resposta da pesquisa incluirá os valores dos campos title, author e address.city .

Conclusão

Em conclusão, a exibição de campos em um índice do Elasticsearch pode ser realizada usando a API _mapping para recuperar informações do campo e a API _search para exibir os valores do campo. Você pode filtrar os campos retornados na resposta da pesquisa usando os parâmetros _source ou fields e exibir campos aninhados usando a notação de ponto. Essas técnicas podem ajudá-lo a entender a estrutura de seus dados, identificar campos específicos e solucionar problemas.

Neste artigo, discutiremos os motivos para excluir campos da indexação, como configurar o Elasticsearch para excluir campos específicos e algumas práticas recomendadas a serem seguidas ao fazer isso.

Motivos para excluir campos da indexação

1. Desempenho: Indexar todos os campos de um documento pode aumentar o tempo de indexação e tornar a pesquisa mais lenta. Ao excluir campos que não são necessários para pesquisa ou agregação, você pode melhorar o desempenho geral do seu cluster Elasticsearch.

2. Armazenamento: A indexação de campos consome espaço de armazenamento. Excluir campos que não são necessários para pesquisa ou agregação pode ajudar a reduzir os requisitos de armazenamento do seu cluster Elasticsearch.

3. Tamanho do índice: O tamanho de um índice do Elasticsearch está diretamente relacionado ao número de campos indexados. Ao excluir campos desnecessários, você pode minimizar o tamanho do seu índice, o que pode levar a um desempenho de pesquisa e indexação mais rápido.

Configurando o Elasticsearch para excluir campos

Para excluir um campo da indexação no Elasticsearch, você pode usar a propriedade "index" no mapeamento do campo. Ao definir a propriedade “index” como “false”, o Elasticsearch não indexará o campo, e ele não será pesquisável nem estará disponível para agregações.

Aqui está um exemplo de como excluir um campo da indexação usando o mapeamento do Elasticsearch:

Neste exemplo, estamos criando um novo índice chamado “my_index” com um único campo chamado “field_to_exclude”. Ao definir a propriedade “index” como “false”, estamos dizendo ao Elasticsearch para não indexar esse campo. O campo ainda estará disponível no documento original.

Melhores práticas para excluir campos da indexação

1. Analise seus dados: Antes de excluir campos da indexação, é essencial analisar seus dados e entender quais campos são necessários para pesquisa e agregação. Isso ajudará você a tomar decisões informadas sobre quais campos excluir.

2. Teste suas alterações: Ao excluir campos da indexação, é crucial testar as alterações para garantir que a funcionalidade de pesquisa e agregação continue funcionando conforme o esperado. Isso pode ajudar você a evitar problemas inesperados ou falhas de desempenho.

3. Monitore o desempenho: após excluir campos da indexação, monitore o desempenho do seu cluster Elasticsearch para garantir que as alterações tenham surtido o efeito desejado. Isso pode ajudar a identificar quaisquer otimizações adicionais que possam ser necessárias.

4. Utilize a filtragem por origem: Se você precisa armazenar um campo no Elasticsearch, mas não deseja que ele seja pesquisável ou disponível para agregações, considere usar a filtragem por origem. Isso permite armazenar o campo no campo _source, mas excluí-lo do índice.

Conclusão

Excluir campos da indexação no Elasticsearch pode ajudar a melhorar o desempenho, reduzir os custos de armazenamento e minimizar o tamanho geral do seu índice. Ao analisar cuidadosamente seus dados e entender quais campos são necessários para pesquisa e agregação, você pode tomar decisões informadas sobre quais campos excluir. Sempre teste suas alterações e monitore o desempenho do seu cluster Elasticsearch para garantir que suas otimizações tenham o efeito desejado.

• As definições de mapeamento especificam o esquema de dados.

• As configurações definem o tamanho dos fragmentos e as taxas de atualização. 

• Os aliases são usados para dar nomes alternativos ao índice.

Ao indexar um documento pela primeira vez ou criar um índice vazio usando a API Criar Índice, o índice será criado com as configurações padrão, sem esquema de dados e sem aliases. Essas configurações padrão funcionam muito bem em ambientes de desenvolvimento e teste, mas talvez seja necessário personalizar nossos índices para ambientes de produção.

Trabalhar com os mapeamentos e configurações padrão em produção pode resultar em indexação e desempenho de pesquisa deficientes. A criação manual de índices é um processo tedioso e demorado. Recriar esses índices em todos os ambientes é especialmente impraticável se tivermos um esquema de mapeamento complexo, além de configurações e aliases personalizados.

Felizmente, o Elasticsearch nos fornece uma ferramenta para aplicar automaticamente uma configuração predefinida ao criar índices na forma de modelos de índice .

Modelos de índice

Os modelos de índice permitem criar índices com configurações definidas pelo usuário. Um índice pode obter a configuração desses modelos, por exemplo, um número definido de shards e réplicas ou mapeamentos de campos, durante sua instanciação. Um modelo será definido com um padrão de nome e algumas configurações. Se o nome do índice corresponder ao padrão de nomenclatura do modelo, o novo índice será criado com a configuração definida no modelo.

O Elasticsearch atualizou sua funcionalidade de modelos na versão 7.8 com modelos compostos. Esta versão mais recente oferece muito mais modelos de índice reutilizáveis, como demonstrado neste artigo.

Tipos de modelo de índice

Os modelos de índice podem ser classificados em duas categorias:

• Modelos de índice (ou modelos de índice componíveis): Os modelos de índice componíveis podem existir por si só ou podem ser compostos por nenhum ou mais modelos componentes (consulte a segunda categoria).

• Modelos de componentes: O modelo de componente é um modelo reutilizável que define a configuração necessária. Normalmente, espera-se que o modelo de componente esteja associado a um modelo de índice. Cada um dos modelos de componentes pode ser associado a um ou mais modelos de índice. 

Como você pode ver na imagem abaixo, os modelos de índice A e B compartilham modelos de componentes (neste caso, apenas um – o Modelo 3) entre si. Um modelo de índice pode não conter nenhum ou vários modelos de componentes, e cada um dos modelos de componentes pode não estar associado a nenhum ou a vários modelos de índice. Ambos os tipos de modelos podem existir por si só, porém os modelos de componentes são inúteis a menos que estejam anexados a um modelo de índice.

A ideia geral é desenvolver um catálogo de modelos de componentes para uma organização usar em diversas necessidades (por exemplo, especificar os vários modelos de componentes para ambientes individuais) e associá-los a vários índices por meio de modelos de índice componíveis.

Como criar modelos (de índice) componíveis

O Elasticsearch fornece um endpoint _index_template para gerenciar modelos de índice. Neste modelo, o usuário fornece todos os mapeamentos, configurações e aliases necessários, juntamente com um padrão de nome de índice. Vamos analisar um exemplo de criação de um modelo para um aplicativo de microsserviços chamado customer-order-service , responsável pela lógica de geração de pedidos. 

Digamos que nossa necessidade seja criar um modelo para pedidos de clientes, representado por um padrão com caracteres curinga: *pedidos. Espera-se que este modelo tenha determinados mapeamentos e configurações, como o campo order_date, bem como números de shards e réplicas.

Qualquer índice que corresponda a este modelo durante a sua criação herdará as configurações definidas neste modelo. Por exemplo, um índice black_friday_orders terá o campo order_date, o número de shards será definido como 5 e o número de réplicas como 2. Além disso, todos os índices criados a partir deste modelo também herdarão um único nome de alias ! Vamos criar este modelo de pedidos (orders_template) com um padrão de índice definido como *orders e com um esquema de mapeamento que consiste em um único campo order_date com um formato de data predefinido dd-MM-yyyy. O código abaixo mostra como criar esse modelo de índice.

Ao executar essa consulta nas DevTools do Kibana, o modelo é criado com o padrão de índice *orders, juntamente com o mapeamento predefinido, as configurações e um alias. O `index_patterns` é uma matriz de padrões de correspondência; qualquer índice que corresponda a esse padrão derivará a configuração do modelo. Você pode executar o seguinte comando para recuperar o modelo persistido, que deverá reiterar o que fizemos:

Existe também uma prioridade, um número positivo, definida ao criar o atributo de modelo definido no modelo: cada modelo é definido com uma prioridade, de forma que quaisquer alterações conflitantes de modelos diferentes sejam resolvidas usando esse valor, com precedência dada ao valor de prioridade mais alto. A seguir, analisaremos a prioridade dos modelos com mais detalhes.

Criando um índice com o modelo

Agora que temos um modelo – um projeto para criar índices – o próximo passo é criar um índice. Quando o nome do índice corresponde ao padrão fornecido, as configurações do modelo são aplicadas automaticamente. Para comprovar esse ponto, como mostra o código abaixo, vamos criar um novo índice chamado: blackfriday_orders:

Como o nome do índice (blackfriday_orders) corresponde ao padrão de nomenclatura definido no modelo (ou seja, *pedidos), o índice deve obter toda a configuração derivada do modelo. Vamos recuperar esse índice recém-criado e verificar se isso é realmente verdade executando o seguinte código:

Isso deve retornar:

Conforme indicado na resposta, a configuração do blackfriday_orders foi herdada do modelo. Podemos tentar várias combinações de índices que herdarão com sucesso a configuração do modelo:

No entanto, os seguintes índices não herdarão a configuração, pois o nome não corresponderá ao padrão:

Um ponto importante a lembrar é que todos os índices derivados de um modelo têm o mesmo alias – all_orders – neste caso. Existe uma vantagem em ter um alias desse tipo: podemos simplesmente consultar esse único alias em vez de vários índices.

Embora criemos um modelo para *pedidos, espera-se que qualquer índice correspondente adote a configuração do modelo. Normalmente, consciente ou inconscientemente, as equipes podem criar alguns modelos adicionais por diversos motivos. Isso significa que, às vezes, o nome do índice pode corresponder a dois padrões de modelo diferentes! O Elasticsearch precisa decidir qual das configurações desses modelos deve ser aplicada. Felizmente, esse dilema pode ser resolvido usando a prioridade do modelo.

Como criar modelos de componentes

Aprendemos sobre modelos de índice na parte anterior deste artigo. Existem algumas desvantagens em criar modelos com a configuração já integrada – uma delas é que a configuração não pode ser exportada para outros modelos. Se desejarmos ter uma configuração semelhante, por exemplo, para modelos relacionados a clientes (*clientes), talvez tenhamos que recriar todo o modelo. Isso significa que podemos estar criando dezenas deles em uma organização típica (e você pode ter alguns outros dependendo do ambiente).

Como sempre buscamos a reutilização, o Elasticsearch redesenhou os modelos levando isso em consideração. Os modelos de componentes atendem a essa necessidade. Se você tem experiência em DevOps, provavelmente precisará criar índices com uma configuração predefinida para cada um dos ambientes. Em vez de aplicar manualmente cada uma dessas configurações de forma tediosa, você pode criar um modelo de componente para cada um dos ambientes.

Um modelo de componente nada mais é do que um bloco reutilizável de configurações que podemos usar para criar mais modelos de índice. Note que os modelos de componentes não têm utilidade a menos que sejam combinados com modelos de índice. Eles são expostos através de um endpoint _component_template. Vamos ver como tudo isso se encaixa.

Configurações em um modelo de índice

Vamos extrair as configurações que definimos anteriormente em nosso modelo de índice e criar um modelo de componente a partir delas. Espera-se que o settings_component_template tenha cinco shards primários com duas réplicas por shard primário. O primeiro passo, como mostra o código abaixo, é declarar e executar um modelo de componente com essa configuração.

Como mostra o código acima, usamos o endpoint _component_template para criar um modelo de componente. O corpo da solicitação contém as informações do modelo em um objeto de modelo. O modelo settings_component_template agora está disponível para uso em outros locais nos modelos de índice. Uma diferença notável é que este modelo não define nenhum padrão de índice; é simplesmente um bloco de código que configura algumas propriedades para nós.

Modelo de mapeamento

Da mesma forma, vamos criar outro modelo. Desta vez, vamos extrair o esquema de mapeamento que definimos anteriormente nos modelos de índice independentes. O código abaixo mostra o script:

Modelo de aliases

Seguindo a mesma linha de raciocínio, também podemos ter um modelo de componente com os aliases – dois aliases (all_orders e sales_orders):

Modelo de índice componível

Agora que temos esses três modelos de componentes, o próximo passo é colocá-los em uso. Podemos fazer isso permitindo que um modelo de índice, digamos, para pedidos de Natal, o utilize:

A tag `composed_of` é uma coleção de todos os modelos de componentes que compõem este modelo. Neste caso, estamos escolhendo as configurações, os mapeamentos e os modelos de componentes de aliases. Também estamos aumentando a prioridade, então este modelo terá precedência sobre qualquer outro. Assim que o modelo estiver pronto, quaisquer índices que correspondam ao padrão *orders herdarão a configuração desses três modelos de componentes.

Dito isso, caso desejemos criar um novo modelo, digamos, para clientes, utilizando apenas um dos modelos existentes (settings_component_template) e um modelo de aliases recém-criado (aliases_component_template – veja abaixo), podemos fazê-lo da seguinte forma:

O modelo de índice é o seguinte:

Você percebeu que o settings_component_template foi (re)utilizado em dois templates diferentes? Esse é o poder dos modelos de componentes.

Prioridade do modelo de índice

Existe a possibilidade de os desenvolvedores criarem vários modelos de índice sem analisar o estoque existente. É importante definir uma prioridade para cada um desses modelos, de forma que aquele com maior prioridade seja utilizado. Por exemplo, o modelo `my_orders_template_1` sobrescreve o modelo `my_orders_template_2` no seguinte trecho de código:

Quando você tem vários modelos que correspondem aos índices que estão sendo criados, o Elasticsearch aplica todas as configurações de todos os modelos correspondentes, mas sobrescreve qualquer configuração que tenha prioridade mais alta.

Precedência dos modelos

Por fim, você pode estar se perguntando sobre a precedência dos modelos – a configuração definida no modelo do componente substitui a definida no próprio modelo do índice principal? Ou vice-versa? Bem, existem algumas regras:

• Um índice criado com configurações explícitas tem precedência sobre tudo – isso significa que, se você criar um índice com configuração explícita, não espere que ela seja substituída pelos modelos.

• Os modelos legados (modelos criados antes da versão 7.8) têm uma prioridade menor do que os modelos componíveis.

Resumo

• Um índice contém mapeamentos, configurações e aliases: os mapeamentos definem o esquema dos campos, as configurações definem os parâmetros do índice, como o número de shards e réplicas, e os aliases fornecem nomes alternativos ao índice.

• Os modelos permitem criar índices com configurações predefinidas. Ao atribuir um nome a um índice que corresponda ao padrão de índice definido em um modelo específico, esse índice será configurado automaticamente de acordo com o modelo.

• O Elasticsearch introduziu modelos de índice componíveis na versão 7.8. Os modelos de índice combináveis permitem modularidade e versionamento dos modelos.

• Os modelos componíveis consistem em nenhum ou mais modelos de componentes.

• Um modelo de índice também pode ter sua própria configuração definida.

• Um modelo de componente é um modelo reutilizável com configuração predefinida, assim como um modelo de índice composto.

• No entanto, espera-se que os modelos de componentes façam parte de um modelo de índice; eles são inúteis se não forem "compostos" em um modelo de índice.

• Os modelos de componentes não têm um padrão de índice definido neles – o que é mais um motivo pelo qual "se espera" que façam parte de um modelo de índice.

• Cada um dos modelos tem uma prioridade – um número positivo. Quanto maior o número, maior a prioridade para a aplicação desse modelo.

Neste artigo, explicaremos como configurar o Airbyte para ingerir dados no Elasticsearch, abordando conceitos-chave, pré-requisitos e integração passo a passo.

Conceitos fundamentais do Airbyte

O Airbyte possui diversos conceitos essenciais para sua utilização. A seguir, destacamos os principais:

• Fontes: Define a origem dos dados que serão extraídos.

• Destinos: Define onde os dados serão enviados e armazenados.

• Conexões: Configura a relação entre a origem e o destino, incluindo a frequência de sincronização.

Integração do Airbyte com o Elasticsearch

Nesta demonstração, realizaremos uma integração onde os dados armazenados em um bucket do S3 serão migrados para um índice do Elasticsearch. Mostraremos como configurar a origem (S3) e o destino (Elasticsearch) no Airbyte.

Pré-requisitos

Para acompanhar esta demonstração, os seguintes pré-requisitos devem ser atendidos:

1. Crie um bucket na AWS onde os arquivos JSON contendo os dados serão armazenados.

2. Instale o Airbyte localmente usando o Docker.

3. Crie um cluster Elasticsearch no Elastic Cloud para armazenar os dados ingeridos.

A seguir, detalharemos cada uma dessas etapas.

Instalando o Airbyte

O Airbyte pode ser executado localmente usando o Docker ou na nuvem, onde existem custos associados ao uso. Para esta demonstração, usaremos a versão local com Docker.

A instalação pode levar alguns minutos. Após seguir as instruções de instalação, o Airbyte estará disponível em: http://localhost:8000.

Após efetuar o login, podemos começar a configurar a integração.

Criando o balde

Nesta etapa, você precisará de uma conta da AWS para criar um bucket do S3. Além disso, é essencial definir as permissões corretas criando uma política e um usuário IAM para permitir o acesso ao bucket.

No bucket, carregaremos arquivos JSON contendo diferentes registros de log, que posteriormente serão migrados para o Elasticsearch. Os arquivos de registro contêm o seguinte:

Abaixo estão os arquivos carregados no bucket:

Configuração do Elastic Cloud

Para facilitar a demonstração, usaremos o Elastic Cloud. Se você ainda não possui uma conta, pode criar uma conta de avaliação gratuita aqui: Cadastro no Elastic Cloud.

Após configurar a implantação no Elastic Cloud, você precisará obter:

• O URL do servidor Elasticsearch.

• Um usuário para acessar o Elasticsearch.

Para obter a URL, acesse Implantações > Minha implantação, em Aplicativo, encontre Elasticsearch e clique em 'Copiar endpoint'.

Para criar o usuário, siga os passos abaixo:

1. Acesse Kibana > Gerenciamento de Pilha > Usuários.

2. Crie um novo usuário com a função de superusuário.

3. Preencha os campos para criar o usuário.

Agora que está tudo configurado, podemos começar a configurar os conectores no Airbyte.

Configurando o conector de origem

Nesta etapa, criaremos o conector de origem para o S3. Para isso, acessaremos a interface do Airbyte e selecionaremos a opção Fonte no menu. Em seguida, procuraremos o conector S3. A seguir, detalhamos os passos necessários para configurar o conector:

1. Acesse o Airbyte e vá para o menu Fontes.

2. Procure e selecione o conector S3.

3. Configure os seguintes parâmetros:

   1. Nome da fonte: Defina um nome para a fonte de dados.

   2. Método de entrega: Selecione "Replicar registros" (recomendado para dados estruturados).

   3. Formato de dados: Selecione o formato JSON.

   4. Nome do fluxo: Defina o nome do índice no Elasticsearch.

   5. Nome do bucket: Insira o nome do bucket na AWS.

   6. Chave de acesso da AWS e chave secreta da AWS: Insira as credenciais de acesso.

Clique em Configurar fonte e aguarde a validação.

Conector de destino de configuração

Nesta etapa, configuraremos o conector de destino, que será o Elasticsearch. Para isso, acessaremos o menu e selecionaremos a opção Destino. Em seguida, pesquisaremos por Elasticsearch e clicaremos no resultado retornado. Agora, vamos prosseguir com a configuração desta conexão:

1. Acesse o Airbyte e vá para o menu Destinos.

2. Pesquise e selecione o conector Elasticsearch.

3. Configure os seguintes parâmetros:

   1. Método de autenticação: Escolha Nome de usuário/Senha.

   2. Nome de usuário e senha: Utilize as credenciais criadas no Kibana.

   3. Endpoint do servidor: Cole a URL copiada do Elastic Cloud.

Clique em Configurar destino e aguarde a validação.

Criando a conexão de origem e destino

Após a criação da Origem e do Destino, a conexão entre eles será estabelecida, concluindo assim a integração.

A seguir, as instruções para criar a conexão:

1. No menu, acesse Conexões e clique em Criar primeira conexão.

2. Na tela seguinte, você poderá selecionar uma fonte existente ou criar uma nova. Como já temos uma Origem criada, selecionaremos a Origem S3.

3. O próximo passo será selecionar o destino. Como já criamos o conector Elasticsearch, ele será selecionado para finalizar a configuração.

Na próxima etapa, será necessário definir o Modo de Sincronização e qual esquema será utilizado. Como apenas o esquema de log foi criado, essa será a única opção disponível para seleção.

4. Vamos prosseguir para a etapa de Configuração de Conexão. Aqui, podemos definir o nome da conexão e a frequência de execução da integração. A frequência pode ser configurada de três maneiras:

• Cron: Executa as sincronizações com base na expressão cron definida pelo usuário (ex: 0 0 15 * * ?, Às 15:00 todos os dias);

• Agendado: Executa as sincronizações no intervalo de tempo especificado (por exemplo, a cada 24 horas, a cada 2 horas);

• Manual: Execute as sincronizações manualmente.

Para esta demonstração, selecionaremos a opção Manual.

Por fim, ao clicar em Configurar conexão, a conexão entre a origem e o destino será estabelecida.

Sincronizando dados do S3 para o Elasticsearch

Ao retornar à tela Conexões, você poderá ver a conexão que foi criada. Para executar o processo, basta clicar em Sincronizar. A partir desse momento, terá início a migração de dados do S3 para o Elasticsearch.

Se tudo correr bem, você receberá o status de sincronização.

Visualizando dados no Kibana

Agora, vamos ao Kibana para analisar os dados e verificar se foram indexados corretamente. Na seção Kibana Discovery, criaremos uma visualização de dados chamada logs. Com isso, poderemos explorar os dados existentes apenas no índice de logs, que foi criado após a sincronização.

Agora podemos visualizar os dados indexados e realizar análises sobre eles. Dessa forma, validamos todo o fluxo de migração usando o Airbyte, onde carregamos os dados presentes no bucket e os indexamos no Elasticsearch.

Conclusão: Integração do Airbyte e do Elasticsearch

O Airbyte provou ser uma ferramenta eficiente para integração de dados, permitindo-nos conectar diversas fontes e destinos de forma automatizada. Neste tutorial, demonstramos como ingerir dados de um bucket S3 em um índice Elasticsearch, destacando as principais etapas do processo.

Essa abordagem facilita a ingestão de grandes volumes de dados e permite análises dentro do Elasticsearch, como buscas complexas, agregações e visualizações de dados.

Referências

Guia rápido do Airbyte:

https://docs.airbyte.com/using-airbyte/getting-started/oss-quickstart#part-1-install-abctl

Conceitos básicos:

https://docs.airbyte.com/using-airbyte/core-concepts/

O que é o LlamaIndex?

O LlamaIndex é uma estrutura que facilita a criação de agentes e fluxos de trabalho baseados em Modelos de Linguagem de Grande Porte (LLMs, na sigla em inglês) para interagir com dados específicos ou privados. Permite a integração de dados de diversas fontes (APIs, PDFs, bases de dados) com LLMs, possibilitando tarefas como pesquisa, extração de informações e geração de respostas contextualizadas.

Conceitos-chave:

• Agentes: Assistentes inteligentes que utilizam LLMs para executar tarefas, desde respostas simples até ações complexas.

• Fluxos de trabalho: Processos de várias etapas que combinam agentes, conectores de dados e ferramentas para tarefas avançadas.

• Aumento de contexto: uma técnica que enriquece o modelo de aprendizagem linear (LLM) com dados externos, superando suas limitações de treinamento.

Integração do LlamaIndex com o Elasticsearch:

O Elasticsearch pode ser usado de diversas maneiras com o LlamaIndex:

• Fonte de dados: Utilize o Elasticsearch Reader para extrair os documentos.

• Modelo de embeddings: Codifica dados em vetores para buscas semânticas.

• Armazenamento vetorial: Utilize o Elasticsearch como repositório para busca de documentos vetorizados.

• Armazenamento avançado: configure estruturas como resumos de documentos ou grafos de conhecimento.

Utilizando LlamaIndex e Elasticsearch para construir uma busca de perguntas frequentes (FAQ).

Preparação de dados

Usaremos as Perguntas Frequentes do Elasticsearch Service como exemplo. Cada pergunta foi extraída do site e salva em um arquivo de texto individual. Você pode usar qualquer abordagem para organizar os dados; neste exemplo, optamos por salvar os arquivos localmente.

Arquivo de exemplo:

Após salvar todas as perguntas, o diretório ficará assim:

Instalação de dependências

Implementaremos a ingestão e a pesquisa usando a linguagem Python, sendo a versão utilizada a 3.9. Como pré-requisito, será necessário instalar as seguintes dependências:

O Elasticsearch e o Kibana serão criados com o Docker, configurados via docker-compose.yml para executar a versão 8.16.2. Isso facilita a criação do ambiente local.

Ingestão de documentos usando LlamaIndex

Os documentos serão indexados no Elasticsearch usando o LlamaIndex. Primeiro, carregamos os arquivos com SimpleDirectoryReader, que permite carregar arquivos de um diretório local. Após carregar os documentos, iremos indexá-los usando o VectorStoreIndex.

Os Vector Stores no LlamaIndex são responsáveis por armazenar e gerenciar incorporações de documentos. O LlamaIndex suporta diferentes tipos de armazenamentos vetoriais e, neste caso, usaremos o Elasticsearch. No StorageContext, configuramos a instância do Elasticsearch. Como o contexto é local, não foram necessários parâmetros adicionais. Para configurações em outros ambientes, consulte a documentação para verificar os parâmetros necessários: Configuração do ElasticsearchStore.

Por padrão, o LlamaIndex usa o modelo text-embedding-ada-002 da OpenAI para gerar embeddings. No entanto, neste exemplo, usaremos o modelo text-embedding-3-small . É importante ressaltar que será necessária uma chave de API da OpenAI para usar o modelo.

Abaixo está o código completo para ingestão de documentos.

Após a execução, os documentos serão indexados no índice de perguntas frequentes , conforme mostrado abaixo:

Pesquisar com RAG

Para realizar buscas, configuramos o cliente ElasticsearchStore , definindo os campos index_name e es_url com a URL do Elasticsearch. Em retrieval_strategy, definimos a AsyncDenseVectorStrategy para buscas vetoriais. Outras estratégias, como AsyncBM25Strategy (busca por palavra-chave) e AsyncSparseVectorStrategy (vetores esparsos), também estão disponíveis. Mais detalhes podem ser encontrados na documentação oficial.

Em seguida, será criado um objeto VectorStoreIndex , onde configuraremos o vector_store usando o objeto ElasticsearchStore. Com o método as_retriever , realizamos a busca pelos documentos mais relevantes para uma consulta, definindo o número de resultados retornados para 5 através do parâmetro similarity_top_k .

O próximo passo é o RAG. Os resultados da busca vetorial são incorporados a um prompt formatado para o LLM, permitindo uma resposta contextualizada com base nas informações recuperadas.

No PromptTemplate, definimos o formato do prompt, que inclui:

• Contexto ({context_str}): documentos recuperados pelo recuperador.

• Consulta ({query_str}): a pergunta do usuário.

• Instruções: diretrizes para o modelo responder com base no contexto, sem depender de conhecimento externo.

Por fim, o LLM processa a solicitação e retorna uma resposta precisa e contextualizada.

O código completo está abaixo:

Agora podemos realizar nossa busca, por exemplo, "Os serviços da Elastic são gratuitos?" e obter uma resposta contextualizada com base nos próprios dados das perguntas frequentes.

Para gerar esta resposta, foram utilizados os seguintes documentos:

Conclusão

Utilizando o LlamaIndex, demonstramos como criar um sistema de busca de FAQs eficiente com suporte para o Elasticsearch como banco de dados vetorial. Os documentos são ingeridos e indexados usando incorporações, possibilitando buscas vetoriais. Por meio de um PromptTemplate, os resultados da pesquisa são incorporados ao contexto e enviados ao LLM, que gera respostas precisas e contextualizadas com base nos documentos recuperados.

Este fluxo de trabalho integra a recuperação de informações com a geração de respostas contextualizadas para fornecer resultados precisos e relevantes.

Referências

https://www.elastic.co/guide/en/cloud/current/ec-faq-getting-started.html

https://docs.llamaindex.ai/en/stable/api_reference/readers/elasticsearch/

https://docs.llamaindex.ai/en/stable/module_guides/indexing/vector_store_index/

https://docs.llamaindex.ai/en/stable/examples/query_engine/custom_query_engine/

https://www.elastic.co/search-labs/integrations/llama-index

O Apache Airflow é uma plataforma projetada para criar, agendar e monitorar fluxos de trabalho. É utilizado para orquestrar processos ETL, pipelines de dados e outros fluxos de trabalho complexos, oferecendo flexibilidade e escalabilidade. Sua interface visual e recursos de monitoramento em tempo real tornam o gerenciamento de pipelines mais acessível e eficiente, permitindo acompanhar o progresso e os resultados de suas execuções. Abaixo estão seus quatro pilares principais:

• Dinâmico: Os pipelines são definidos em Python, permitindo a geração de fluxos de trabalho dinâmicos e flexíveis.

• Extensível: O Airflow pode ser integrado a uma variedade de ambientes, operadores personalizados podem ser criados e códigos específicos podem ser executados conforme necessário.

• Elegante: os pipelines são escritos de forma clara e explícita.

• Escalável: Sua arquitetura modular utiliza uma fila de mensagens para orquestrar um número arbitrário de trabalhadores.

Na prática, o Airflow pode ser usado em cenários como:

• Importação de dados: Orquestre a ingestão diária de dados em um banco de dados como o Elasticsearch.

• Monitoramento de logs: Gerencie a coleta e o processamento de arquivos de log, que são então analisados no Elasticsearch para identificar erros ou anomalias.

• Integração de múltiplas fontes de dados: Combine informações de diferentes sistemas (APIs, bancos de dados, arquivos) em uma única camada no Elasticsearch, simplificando a busca e a geração de relatórios.

Entendendo os DAGs (Grafos Acíclicos Direcionados) no fluxo de ar

No Airflow, os fluxos de trabalho são representados por DAGs (Grafos Acíclicos Direcionados). Um DAG (Grafo Acíclico Direcionado) é uma estrutura que define a sequência em que as tarefas serão executadas. As principais características dos DAGs são:

• Composição por tarefas independentes: Cada tarefa representa uma unidade de trabalho e foi concebida para ser executada de forma independente.

• Sequenciamento: A sequência em que as tarefas são executadas é definida explicitamente no DAG (grafo acíclico direcionado).

• Reutilização: os DAGs são projetados para serem executados repetidamente, facilitando a automação de processos.

Componentes do fluxo de ar

O ecossistema Airflow é composto por diversos componentes que trabalham em conjunto para orquestrar tarefas:

• Agendador: Responsável por agendar DAGs e enviar tarefas para execução pelos workers.

• Executor: Gerencia a execução de tarefas, delegando-as aos trabalhadores.

• Servidor Web: Fornece uma interface gráfica para interação com DAGs e tarefas.

• Pasta DAGs: Pasta onde armazenamos os DAGs escritos em Python.

• Metadados: Banco de dados que serve como repositório para a ferramenta, usado pelo agendador e pelo executor para armazenar o status da execução.

Apache Airflow e Elasticsearch

Iremos demonstrar o uso do Apache Airflow e do Elasticsearch para orquestrar tarefas e indexar resultados no Elasticsearch. O objetivo desta demonstração é criar um fluxo de tarefas para atualizar registros em um índice do Elasticsearch. Este índice contém um banco de dados de filmes, onde os usuários podem avaliar e atribuir notas. Imaginando um cenário com centenas de avaliações diárias, é necessário manter o registro de avaliações atualizado. Para isso, será desenvolvido um DAG (Grafo Acíclico Direcionado) que será executado diariamente, responsável por obter as novas classificações consolidadas e atualizar os registros no índice.

No fluxo DAG, teremos uma tarefa para obter as classificações, seguida de uma tarefa para validar os resultados. Caso os dados não existam, o DAG será direcionado para uma tarefa de falha. Caso contrário, os dados serão indexados no Elasticsearch. O objetivo é atualizar o campo de classificação de filmes em um índice, recuperando as classificações por meio de um método com o mecanismo responsável pelo cálculo das pontuações.

Utilizando Apache Airflow e Elasticsearch com Docker

Para criar um ambiente conteinerizado, usaremos o Apache Airflow com o Docker. Siga as instruções do guia "Executando o Airflow no Docker" para configurar o Airflow na prática.

Quanto ao Elasticsearch, usarei um cluster no Elastic Cloud, mas, se preferir, você também pode configurar o Elasticsearch com o Docker. Já foi criado um índice contendo um catálogo de filmes, com os dados dos filmes indexados. O campo de 'classificação' desses filmes será atualizado.

Criando o DAG

Após a instalação via Docker, será criada uma estrutura de pastas, incluindo a pasta dags, onde devemos colocar nossos arquivos DAG para que o Airflow os reconheça.

Antes disso, precisamos garantir que as dependências necessárias estejam instaladas. Aqui estão as dependências deste projeto:

Criaremos o arquivo update_ratings_movies.py e começaremos a codificar as tarefas.

Agora, vamos importar as bibliotecas necessárias:

Usaremos o ElasticsearchPythonHook, um componente que simplifica a integração entre o Airflow e um cluster Elasticsearch, abstraindo a conexão e o uso de APIs externas.

Em seguida, definimos o DAG, especificando seus principais argumentos:

• dag_id: o nome do DAG.

• start_date: quando o DAG será iniciado.

• schedule: define a periodicidade (diária no nosso caso).

• doc_mdDocumentação que será importada e exibida na interface do Airflow.

Definindo as tarefas

Agora, vamos definir as tarefas do DAG. A primeira tarefa será responsável por obter os dados de classificação dos filmes. Usaremos o PythonOperator com o task_id definido como 'get_movie_ratings'. O parâmetro python_callable chamará a função responsável por obter as classificações.

Em seguida, precisamos validar se os resultados são válidos. Para isso, usaremos uma condicional com um BranchPythonOperator. O task_id será 'validate_result' e o python_callable chamará a função de validação. O parâmetro op_args será usado para passar o resultado da tarefa anterior, 'get_movie_ratings', para a função de validação.

Se a validação for bem-sucedida, pegaremos os dados da tarefa 'get_movie_ratings' e os indexaremos no Elasticsearch. Para alcançar isso, criaremos uma nova tarefa, 'index_movie_ratings', que usará o PythonOperator. O parâmetro op_args passará os resultados da tarefa 'get_movie_ratings' para a função de indexação.

Se a validação indicar uma falha, o DAG prosseguirá para uma tarefa de notificação de falha. Neste exemplo, simplesmente imprimimos uma mensagem, mas em um cenário real, poderíamos configurar alertas para notificar sobre as falhas.

Por fim, definimos as dependências das tarefas, garantindo que elas sejam executadas na ordem correta:

Segue agora o código completo do nosso DAG:

Visualizando a execução do DAG

Na interface do Apache Airflow, podemos visualizar a execução dos DAGs (grafos acíclicos direcionados). Basta acessar a aba "DAGs" e localizar o DAG que você criou.

Abaixo, podemos visualizar a execução das tarefas e seus respectivos status. Ao selecionar uma execução para uma data específica, podemos acessar os registros de cada tarefa. Observe que na tarefa index_movie_ratings , podemos ver os resultados da indexação no índice e que ela foi concluída com sucesso.

Nas outras abas, é possível acessar informações adicionais sobre as tarefas e o DAG, auxiliando na análise e resolução de possíveis problemas.

Conclusão

Neste artigo, demonstramos como integrar o Apache Airflow com o Elasticsearch para criar uma solução de ingestão de dados. Mostramos como configurar o DAG, definir as tarefas responsáveis por recuperar, validar e indexar dados de filmes, bem como monitorar e visualizar a execução dessas tarefas na interface do Airflow.

Essa abordagem pode ser facilmente adaptada a diferentes tipos de dados e fluxos de trabalho, tornando o Airflow uma ferramenta útil para orquestrar pipelines de dados em diversos cenários.

Referências

Apache AirFlow

https://airflow.apache.org/

Instale o Apache Airflow com o Docker.

https://airflow.apache.org/docs/apache-airflow/stable/howto/docker-compose/index.html

Gancho Python do Elasticsearch

https://airflow.apache.org/docs/apache-airflow-providers-elasticsearch/stable/hooks/elasticsearch_python_hook.html

Operador Python

https://airflow.apache.org/docs/apache-airflow/stable/howto/operator/python.html

Pré-requisitos

• Docker e Docker Compose: Certifique-se de ter o Docker e o Docker Compose instalados em sua máquina.

• Python 3.x: Para executar os scripts do produtor e do consumidor.

Introdução ao Apache Kafka

O Apache Kafka é uma plataforma de streaming distribuída que permite alta escalabilidade e disponibilidade, além de tolerância a falhas. No Kafka, o gerenciamento de dados ocorre por meio dos seguintes componentes principais:

• Intermediário (Broker): responsável por armazenar e distribuir mensagens entre produtores e consumidores.

• Zookeeper: gerencia e coordena os brokers do Kafka, controlando o estado do cluster, os líderes de partição e as informações do consumidor.

• Tópicos: canais onde os dados são publicados e armazenados para consumo.

• Consumidores e Produtores: enquanto os produtores enviam dados para os tópicos, os consumidores recuperam esses dados.

Esses componentes trabalham juntos para formar o ecossistema Kafka, fornecendo uma estrutura robusta para streaming de dados.

Estrutura do projeto

Para entender o processo de ingestão de dados, dividimos o processo em etapas:

• Provisionamento de infraestrutura: configuração do ambiente Docker para suportar Kafka, Elasticsearch e Kibana.

• Criação do produtor: implementação do produtor Kafka, que envia dados para o tópico de logs.

• Criação do consumidor: desenvolvimento do consumidor Kafka para ler e indexar mensagens no Elasticsearch.

• Validação de ingestão: verificação e validação dos dados enviados e consumidos.

Configuração de infraestrutura com Docker Compose

Utilizamos o Docker Compose para configurar e gerenciar os serviços necessários. A seguir, você encontrará o código Docker Compose que configura cada serviço necessário para a integração do Apache Kafka, Elasticsearch e Kibana, garantindo um processo de ingestão de dados.

Você pode acessar o arquivo diretamente do repositório GitHub do Elasticsearch Labs.

Envio de dados com o Kafka Producer

O produtor é responsável por enviar mensagens para o tópico de logs. Ao enviar mensagens em lotes, aumenta-se a eficiência do uso da rede, permitindo otimizações com as configurações batch_size e linger_ms , que controlam a quantidade e a latência dos lotes, respectivamente. A configuração acks='all' garante que as mensagens sejam armazenadas de forma durável, o que é essencial para dados de log importantes.

Ao iniciar o produtor, as mensagens são enviadas em lotes para o tópico, conforme mostrado abaixo:

Consumo e indexação de dados com o Kafka Consumer.

O consumidor foi projetado para processar mensagens de forma eficiente, consumindo lotes do tópico de logs e indexando-os no Elasticsearch. Com auto_offset_reset='latest', garante-se que o consumidor comece a processar as mensagens mais recentes, ignorando as mais antigas, e max_poll_records=10 limita o lote a 10 mensagens. Com fetch_max_wait_ms=2000, o consumidor espera até 2 segundos para acumular mensagens suficientes antes de processar o lote.

Em seu loop principal, o consumidor consome mensagens de log, processa e indexa cada lote no Elasticsearch, garantindo a ingestão contínua de dados.

Visualizando dados no Kibana

Com o Kibana, podemos explorar e validar os dados ingeridos do Kafka e indexados no Elasticsearch. Ao acessar as Ferramentas de Desenvolvimento no Kibana, você pode visualizar as mensagens indexadas e confirmar se os dados estão conforme o esperado. Por exemplo, se o nosso produtor Kafka enviar 5 lotes de 10 mensagens cada, devemos ver um total de 50 registros no índice.

Para verificar os dados, você pode usar a seguinte consulta na seção Ferramentas de Desenvolvimento :

Resposta.

Além disso, o Kibana oferece a capacidade de criar visualizações e painéis que podem ajudar a tornar a análise mais intuitiva e interativa. Abaixo, você pode ver alguns exemplos dos painéis e visualizações que criamos, os quais ilustram os dados em vários formatos, aprimorando nossa compreensão das informações processadas.

Ingestão de dados com Kafka Connect

O Kafka Connect é um serviço projetado para facilitar a integração entre fontes de dados e destinos (sinks), como bancos de dados ou sistemas de arquivos. Ele opera com conectores predefinidos que gerenciam a movimentação de dados automaticamente. Em nosso caso, o Elasticsearch funciona como o coletor de dados.

Ao usar o Kafka Connect, podemos simplificar o processo de ingestão de dados, eliminando a necessidade de implementar manualmente o fluxo de trabalho de ingestão de dados no Elasticsearch. Com o conector apropriado, o Kafka Connect permite que os dados enviados para um tópico do Kafka sejam indexados diretamente no Elasticsearch com configuração mínima e sem necessidade de codificação adicional.

Trabalhando com o Kafka Connect

Para implementar o Kafka Connect, adicionaremos o serviço kafka-connect à nossa configuração do Docker Compose. Uma parte fundamental dessa configuração é a instalação do conector Elasticsearch, que ficará responsável pela indexação dos dados.

Após configurar o serviço e criar o contêiner do Kafka Connect, será necessário um arquivo de configuração para o conector do Elasticsearch. Este arquivo define parâmetros essenciais, tais como:

• connection.urlURL de conexão para o Elasticsearch.

• topicsO tópico do Kafka que o conector irá monitorar (neste caso, "logs").

• type.nameTipo de documento no Elasticsearch (normalmente _doc).

• value.converterConverte mensagens do Kafka para o formato JSON.

• value.converter.schemas.enableEspecifica se o esquema deve ser incluído.

• schema.ignore e key.ignore: Configurações para ignorar esquemas e chaves do Kafka durante a indexação.

Abaixo está o comando curl para criar o conector Elasticsearch no Kafka Connect:

Com essa configuração, o Kafka Connect começará automaticamente a ingerir os dados enviados para o tópico "logs" e a indexá-los no Elasticsearch. Essa abordagem permite a ingestão e indexação de dados totalmente automatizadas, sem a necessidade de codificação adicional, simplificando assim todo o processo de integração.

Conclusão

A integração do Kafka e do Elasticsearch cria um poderoso pipeline para ingestão e análise de dados em tempo real. Este guia fornece uma abordagem fundamental para a construção de uma arquitetura robusta de ingestão de dados, com visualização e análise integradas no Kibana, pronta para se adaptar a requisitos mais complexos no futuro.

Além disso, o uso do Kafka Connect torna a integração entre o Kafka e o Elasticsearch ainda mais simplificada, eliminando a necessidade de código adicional para processar e indexar dados. O Kafka Connect permite que os dados enviados para um tópico específico sejam indexados automaticamente no Elasticsearch com configuração mínima.

O que é o Apache Camel?

O Apache Camel é uma estrutura de integração de código aberto que simplifica a conexão de diversos sistemas, permitindo que os desenvolvedores se concentrem na lógica de negócios sem se preocuparem com as complexidades da comunicação entre sistemas. O conceito central do Camel é o de "rotas", que definem o caminho que uma mensagem percorre da origem ao destino, podendo incluir etapas intermediárias como transformações, validações e filtragem.

Arquitetura Apache Camel

O Camel usa "componentes" para se conectar a diferentes sistemas e protocolos, como bancos de dados e serviços de mensagens, e "pontos de extremidade" para representar os pontos de entrada e saída das mensagens. Esses conceitos proporcionam um design modular e flexível, facilitando a configuração e o gerenciamento de integrações complexas de forma eficiente e escalável.

Utilizando Elasticsearch e Apache Camel

Vamos demonstrar como configurar uma aplicação Java simples que utiliza o Apache Camel para ingerir dados em um cluster Elasticsearch. Os processos de criação, atualização e exclusão de dados no Elasticsearch usando rotas definidas no Apache Camel também serão abordados.

1. Adicionando dependências

O primeiro passo para configurar esta integração é adicionar as dependências necessárias ao arquivo pom.xml do seu projeto. Isso incluirá as bibliotecas Apache Camel e Elasticsearch. Usaremos a nova biblioteca Java API Client, portanto, devemos importar o componente camel-elasticsearch e a versão deve ser a mesma da biblioteca camel-core .

Se você deseja usar o cliente REST de baixo nível em Java, deve usar o componente Cliente REST de baixo nível do Elasticsearch.

2. Configurando e executando o contexto do Camel

A configuração começa com a criação de um novo contexto Camel usando a classe DefaultCamelContext , que serve como base para definir e executar rotas. Em seguida, configuramos o componente Elasticsearch, que permitirá que o Apache Camel interaja com um cluster Elasticsearch. A instância ESlasticsearchComponent está configurada para se conectar ao endereço localhost:9200, que é o endereço padrão para um cluster Elasticsearch local. Para uma configuração de ambiente que requer autenticação, você deve ler a documentação sobre como configurar o componente e habilitar a autenticação básica, referida como "Configurar o componente e habilitar a autenticação básica".

Em seguida, esse componente é adicionado ao contexto do Camel, permitindo que as rotas definidas o utilizem para realizar operações no Elasticsearch.

Em seguida, as rotas são adicionadas ao contexto. Criaremos rotas para indexação, atualização e exclusão em massa de documentos.

3. Configurando rotas do Camel

Indexação de dados

A primeira rota que configuraremos é para indexação de dados. Utilizaremos um arquivo JSON contendo um catálogo de filmes. A rota será configurada para ler o arquivo localizado em src/main/resources/movies.json, desserializar o conteúdo JSON em objetos Java e, em seguida, aplicar uma estratégia de agregação para combinar várias mensagens em uma só, permitindo operações em lote no Elasticsearch. O tamanho configurado para 500 itens por mensagem é o seguinte: o processo em lote indexará 500 filmes por vez.

Roteamento Elasticsearch Operação em massa

O lote de documentos será enviado para o endpoint de operações em lote do Elasticsearch. Essa abordagem garante eficiência e rapidez no processamento de grandes volumes de dados.

Atualização de dados

O próximo passo será atualizar os documentos. Na etapa anterior, indexamos alguns filmes e agora criaremos novas rotas para pesquisar um documento por código de referência e, em seguida, atualizar o campo de classificação.

Configuramos um contexto Camel (DefaultCamelContext), onde um componente Elasticsearch é registrado e uma rota personalizada IngestionRoute é adicionada. A operação começa com o envio do código do documento através do ProducerTemplate, que inicia a rota a partir do endpoint direct:update-ingestion.

Em seguida, temos o IngestionRoute, que é o ponto de extremidade de entrada para este fluxo. A rota executa diversas operações em dutos. Primeiro, é feita uma busca no Elasticsearch para localizar o documento pelo código (direct:search-by-id), onde o SearchByCodeProcessor monta a consulta com base no código. Em seguida, o documento recuperado é processado pelo UpdateRatingProcessor, que converte o resultado em objetos Movie, atualiza a classificação do filme para um valor específico e prepara o documento atualizado para ser enviado de volta ao Elasticsearch para atualização.

O processador SearchByCodeProcessor foi configurado apenas para executar a consulta de pesquisa:

O processador UpdateRatingProcessor é responsável por atualizar o campo de classificação.

Exclusão de dados

Por fim, a rota para exclusão de documentos está configurada. Aqui, vamos excluir um documento usando seu ID. No Elasticsearch, para excluir um documento, precisamos saber o identificador do documento, o índice onde o documento está armazenado e executar uma solicitação de exclusão. No Apache Camel, realizaremos essa operação criando uma nova rota, conforme mostrado abaixo.

A rota começa no endpoint direct:op-delete, que serve como ponto de entrada. Quando um documento precisa ser excluído, seu identificador (_id) é recebido no corpo da mensagem. A rota então define o cabeçalho indexId com o valor deste identificador usando simples("${body}"), que extrai o _id do corpo da mensagem.

Por fim, a mensagem é direcionada para o endpoint especificado por URI_DELETE_OPERATION, que se conecta ao Elasticsearch para executar a operação de remoção do documento no índice correspondente. Agora que criamos a rota, podemos criar um contexto Camel (DefaultCamelContext), que está configurado para incluir o componente Elasticsearch.

Em seguida, a rota de exclusão, definida pela classe OperationDeleteRoute , é adicionada ao contexto. Com o contexto inicializado, um ProducerTemplate é usado para passar o identificador do documento que deve ser excluído para o endpoint direct:op-delete , que aciona a rota de exclusão.

Conclusão

A integração entre o Apache Camel e o Elasticsearch permite uma ingestão de dados robusta e eficiente, aproveitando a flexibilidade do Camel para definir rotas que podem lidar com diferentes cenários de manipulação de dados, como indexação, atualização e exclusão. Com essa configuração, você pode orquestrar e automatizar processos complexos de forma escalável, garantindo que seus dados sejam gerenciados com eficiência no Elasticsearch. Este exemplo demonstrou como essas ferramentas podem ser usadas em conjunto para criar uma solução eficiente e adaptável para ingestão de dados.

Referências

• Camelo Apache

• Arquitetura Apache Camel

• Apache Camel agregado

• Componente de arquivo

• componente Elasticsearch