Guion Ruby en Logstash

Elasticsearch te permite indexar datos de manera rápida y flexible. Pruébalo gratis en el cloud o ejecútalo localmente para ver lo fácil que puede ser indexar.

Logstash es una cadena de procesamiento de datos que ingiere datos de múltiples fuentes, los transforma y los envía a los destinos que elijas. Los plugins de filtro son clave para este proceso; Realizan operaciones específicas sobre tus datos a medida que avanzan en la pipeline.

Logstash incluye varios filtros integrados para tareas comunes como análisis sintáctico, enriquecimiento y modificación de datos. Pero a veces te encontrarás con escenarios que requieren una lógica personalizada que va más allá de lo que estos filtros estándar pueden ofrecer. Aquí es donde entra el plugin de filtro Ruby .

El plugin de filtro Ruby te permite ejecutar código Ruby personalizado directamente dentro de tu pipeline de Logstash. Cuando los filtros estándar no son suficientes, el filtro Ruby te permite manejar transformaciones complejas de datos, implementar lógica de negocio personalizada o integrarte con sistemas externos.

En este blog, exploraremos cómo usar los filtros Ruby, desde el uso básico hasta el avanzado.

¿Cuándo deberías usar el filtro Ruby?

Como arquitecto consultor de Elastic, a menudo veo a clientes que emplean Logstash para la cadena de procesamiento de datos, aunque hoy en día no es un motor de procesamiento de datos de última generación. A menudo tienen dificultades con las limitaciones de los filtros estándar cuando se trata de manipulación compleja de datos o lógica personalizada. En estos casos, el filtro Ruby puede ayudar a superar esos desafíos.

El filtro Ruby es útil cuando los filtros Logstash estándar no pueden cumplir tus requisitos específicos. Aquí tienes algunos casos de uso comunes:

• Manipulación profunda de datos anidados: Modificar estructuras JSON complejas, arrays dentro de arrays o reestructurar dinámicamente los datos en función del contenido
• Procesamiento avanzado de cadenas: Analizar y extraer datos estructurados de texto no estructurado
• Implementación de lógica de negocio compleja: Crear transformaciones personalizadas que requieran lógica condicional, bucles o cálculos complejos

Uso básico

Empecemos con un ejemplo sencillo para entender cómo funciona el filtro Ruby.

Configuración del filtro Ruby

Cuando crees una pipeline de Logstash, deberías colocar el archivo de configuración en el directorio /etc/logstash/conf.d . Alternativamente, puedes usar -f opción para especificar la ruta al archivo de configuración cuando arranques Logstash manualmente, para que puedas experimentar fácilmente con tus pipelines.

El archivo de configuración debería tener una extensión .conf .

Para usar el filtro Ruby, define un filtro ruby en la sección de filtros de tu archivo de configuración de la tubería Logstash (*.conf). Aquí tienes un ejemplo básico:

Este filtro Ruby en línea define una instancia de filtro Ruby dentro de tu configuración de Logstash. El parámetro code proporciona el script Ruby en línea que Logstash ejecutará para cada evento procesado por este filtro. Dentro de ese script, hay una variable event disponible que representa el propio evento. El objeto evento contiene los datos originales enviados a Logstash y cualquier campo adicional creado durante las etapas de filtro de Logstash. Puedes acceder a esos campos a través de la API de eventos de Logstash como event.get() y event.set(). En este código de ejemplo, event.set('new_field', 'Hello from Ruby!') establecer un nuevo campo llamado new_field al valor de cadena Hello from Ruby!. Puedes agregar cualquier otro código en este bloque de code según lo necesites.

Ten en cuenta que este objeto event no es un objeto hash de Ruby habitual, aunque actúa como un contenedor de datos clave-valor. Consulta esta documentación oficial para saber más sobre la API de eventos.

Externalizar la escritura Ruby

Para transformaciones simples, el código Ruby en línea es cómodo. Pero, para lógica compleja o funciones reutilizables, se recomienda mover el código a un script Ruby externo. Esto mejora la mantenibilidad y mantiene limpia la configuración de tu pipeline de Logstash.

Primero, crea un script Ruby y almacénalo como my_ruby_script.rb. El script debe definir un método filter que procese el evento. Toma un objeto evento como argumento, que representa el evento actual que se está procesando. El método filter necesita devolver un serial de eventos para emitir. Para eliminar el evento, devuelvo un array vacío.

Por ejemplo, el siguiente script lee el campo message , calcula su longitud y almacena el resultado en un nuevo campo llamado message_length.

A continuación, configura la configuración del filtro Ruby para que haga referencia al script usando la opción path . Esto indica a Logstash que cargue y ejecute el script externo. Al usar scripts externos, cerciórate de que el archivo existe y tiene las licencias correctas.

Ahora, cada evento se pasa al método filter en my_ruby_script.rb y es procesado por él.

Este enfoque te ayuda a gestionar la lógica compleja de forma más eficaz, facilitando probar, depurar y reutilizar tu código Ruby.

Uso avanzado

En esta sección, exploraremos algunos ejemplos avanzados de cómo usar el filtro Ruby en Logstash. Estos ejemplos demostrarán cómo realizar transformaciones de datos, enriquecer eventos e implementar lógica personalizada usando Ruby.

Manipulación de estructuras de datos anidadas

Un evento Logstash es la estructura de datos central que procesa Logstash. Puede contener varios campos, incluyendo estructuras de datos anidadas como arrays y hashes. El filtro Ruby te permite manipular fácilmente estas estructuras anidadas.

El filtro Ruby puede manejar estructuras de datos anidadas, como hashes y arrays, permitiéndote modificar o agregar campos dentro de estas estructuras. Esto es útil cuando se trata de formatos de datos complejos como JSON.

Este ejemplo incluye un objeto JSON anidado en los datos de entrada. El filtro Ruby modifica los datos anidados agregando un nuevo par clave-valor. Este tipo de manipulación para datos anidados no es posible con los filtros Logstash estándar, lo que convierte al filtro Ruby en una opción útil para estructuras de datos complejas.

Dividir un solo evento en varios eventos

Los filtros Ruby también pueden usar para dividir un solo evento en varios eventos. Esto es útil cuando tienes un solo evento que contiene un array de objetos y quieres crear eventos separados para cada uno.

Ten en cuenta que ni la tubería de ingesta de Elasticsearch ni los procesadores de Beats/Elastic Agent soportan eventos de división. Este es uno de los casos de uso más estables de Logstash.

Con filtro dividido

Puedes usar el filtro split para dividir un evento en varios eventos según un campo especificado. Sin embargo, si necesitas realizar transformaciones adicionales o lógica durante la división, puedes usar el filtro Ruby en combinación con el filtro dividido.

En el siguiente ejemplo, tenemos un feed RSS como una sola línea de texto XML. Contiene múltiples elementos <item> . El filtro Ruby se emplea para extraer los <item> elementos del XML y almacenarlos en un nuevo campo llamado items. El filtro dividido se emplea entonces para dividir el evento en varios eventos según el campo items .

Esto dará la siguiente manera:

Como notaste, el filtro ruby no es esencial en este caso. El filtro split puede usar para dividir el evento en varios eventos basados en el campo items , y el filtro mutate puede usar para eliminar campos innecesarios. Sin embargo, si necesitas realizar transformaciones o lógica adicional durante la división, puedes usar el filtro Ruby.

Emplea escritura Ruby en línea

También puedes usar un script Ruby en línea para dividir un solo evento en varios eventos usando el método event.clone y el new_event_block variable, como new_event_block.call(new_event). Esto te permite crear nuevos eventos basados en el evento original mientras se conservan sus datos.

Aquí tienes un ejemplo de cómo usar el filtro Ruby para dividir un solo evento en varios eventos. La entrada y salida son las mismas que en el ejemplo anterior.

Usa un script Ruby externo

También puedes usar un script externo de Ruby para dividir un solo evento en varios eventos.

Archivo de configuración:

El sistema Ruby debe externalizar como split_event.rb:

Recuerda, el método filter debe devolver un serial de eventos. Puedes devolver varios eventos clonando un objeto de evento entrante y agregándolos al array, o puedes devolver un solo evento como un array con un solo elemento.

Esto te permite dividir un solo evento en varios eventos.

Ejecuta comandos externos y analiza su salida

El plugin de entrada ejecutiva de Logstash permite ejecutar comandos externos y su salida será un evento de Logstash. La salida del comando se almacenará en el campo message del evento.

Normalmente, la salida de los comandos del sistema es legible por humanos, pero no está estructurada como JSON u otros formatos que Logstash pueda analizar fácilmente. Para gestionarlo, puedes usar el filtro Ruby para analizar la salida y extraer la información de ella.

Aquí tienes un ejemplo de cómo se emplea el plugin de entrada exec para ejecutar el comando ps -ef , que lista todos los procesos en ejecución en un sistema tipo Unix. La salida será analizada por el filtro Ruby para extraer información relevante sobre cada proceso.

Este ejemplo emplea el plugin de entrada exec para ejecutar el comando ps -ef cada 60 segundos. El filtro Ruby procesa la salida, extrayendo campos relevantes como UID, PID, PPID, uso de la CPU (C), hora de inicio (STIME), TTY, tiempo total de CPU (TIME) y el comando (CMD) ejecutado. Funciona bien en mi entorno macOS, pero puede que tengas que ajustar los patrones regex para que coincidan con el formato de salida del comando ps -ef en tu sistema.

Emplea librerías integradas

El plugin de filtro Ruby permite usar librerías Ruby integradas, que pueden ser muy útiles para diversas tareas. Por ejemplo, puedes usar la librería json para analizar cadenas JSON o la librería date para manipular fechas.

Aquí tienes un ejemplo de cómo usar la librería json para analizar una cadena JSON almacenada en un campo:

Para evitar tener que usar la librería cada vez, deberías externalizar tu código Ruby para poder usar la sentencia require al principio de tu script de filtro Ruby. Esto cargará la biblioteca una vez y la pondrá disponible para tu script.

Para comprobar qué librerías están disponibles en tu entorno, puedes listar las bibliotecas integradas ejecutando el siguiente código en el filtro Ruby:

Nota: Las bibliotecas integradas no son soportadas oficialmente por Logstash, y su comportamiento puede cambiar o puede que no estén disponibles en versiones futuras. Úsalos bajo tu propia responsabilidad.

Conclusión

El filtro Ruby de Logstash te permite personalizar y ampliar las capacidades de tus pipelines de Logstash. En esta publicación, cubrimos lo básico del uso del filtro Ruby y proporcionado ejemplos avanzados de uso.

Aprovechando el filtro Ruby, puedes manejar tareas complejas de procesamiento de datos que requieren lógica personalizada o manipulación avanzada. Ya sea que trabajes con estructuras de datos anidadas, divisiones de eventos o analizes y conviertas textos complejos/no estructurados en JSON estructurado, el filtro Ruby ofrece flexibilidad para satisfacer tus necesidades específicas.

Esperamos que esta guía te proporcionó el conocimiento e inspiración para explorar todo el potencial del filtro Ruby de Logstash. ¡Feliz guion!