Scripting em Ruby no Logstash

O Elasticsearch permite que você indexe dados de maneira rápida e flexível. Experimente gratuitamente na nuvem ou execute-o localmente para ver como a indexação pode ser fácil.

O Logstash é um pipeline de processamento de dados que ingere dados de múltiplas fontes, os transforma e os envia para os destinos escolhidos. Os plugins de filtro são essenciais para esse processo; eles executam operações específicas nos seus dados à medida que estes percorrem o pipeline.

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!