Ruby-Skripting in Logstash

Dai Sugimori — Tue, 24 Jun 2025 00:00:00 GMT

Logstash ist eine Datenverarbeitungspipeline, die Daten aus verschiedenen Quellen aufnimmt, transformiert und an die von Ihnen gewählten Ziele sendet. Filter-Plugins sind für diesen Prozess unerlässlich; sie führen spezifische Operationen an Ihren Daten durch, während diese die Datenpipeline durchlaufen.

Logstash enthält mehrere integrierte Filter für häufige Aufgaben wie das Parsen, Anreichern und Modifizieren von Daten. Manchmal stößt man jedoch auf Szenarien, die eine benutzerdefinierte Logik erfordern, die über das hinausgeht, was diese Standardfilter bieten können. Hier kommt das Ruby-Filter-Plugin ins Spiel.

Mit dem Ruby-Filter-Plugin können Sie benutzerdefinierten Ruby-Code direkt in Ihrer Logstash-Pipeline ausführen. Wenn Standardfilter nicht ausreichen, ermöglicht Ihnen der Ruby-Filter die Durchführung komplexer Datentransformationen, die Implementierung benutzerdefinierter Geschäftslogik oder die Integration mit externen Systemen.

In diesem Blogbeitrag zeigen wir Ihnen, wie Sie Ruby-Filter verwenden – von den Grundlagen bis hin zu fortgeschrittenen Anwendungsfällen.

Wann sollte man den Ruby-Filter verwenden?

Als beratender Architekt bei Elastic sehe ich oft, dass Kunden Logstash für die Datenverarbeitungspipeline verwenden, obwohl es heutzutage keine hochmoderne Datenverarbeitungs-Engine mehr ist. Bei komplexen Datenmanipulationen oder benutzerdefinierter Logik stoßen sie häufig an die Grenzen von Standardfiltern. In diesen Fällen kann der Ruby-Filter dazu beitragen, diese Herausforderungen zu bewältigen.

Der Ruby-Filter ist nützlich, wenn die Standard-Logstash-Filter Ihre spezifischen Anforderungen nicht erfüllen können. Hier einige typische Anwendungsfälle:

Tief verschachtelte Datenmanipulation: Komplexe JSON-Strukturen, Arrays innerhalb von Arrays modifizieren oder Daten dynamisch anhand ihres Inhalts umstrukturieren.
Erweiterte Stringverarbeitung: Strukturierte Daten aus unstrukturiertem Text analysieren und extrahieren
Implementierung komplexer Geschäftslogik: Erstellen benutzerdefinierter Transformationen, die bedingte Logik, Schleifen oder komplexe Berechnungen erfordern.

Grundlegende Verwendung

Beginnen wir mit einem einfachen Beispiel, um zu verstehen, wie der Ruby-Filter funktioniert.

Konfigurieren des Ruby-Filters

Wenn Sie eine Logstash-Pipeline erstellen, sollten Sie die Konfigurationsdatei im Verzeichnis /etc/logstash/conf.d ablegen. Alternativ können Sie die Option -f verwenden, um beim manuellen Starten von Logstash den Pfad zur Konfigurationsdatei anzugeben, sodass Sie problemlos mit Ihren Pipelines experimentieren können.

$ ./bin/logstash -f /path/to/your_pipeline.conf

Die Konfigurationsdatei sollte die Dateiendung .conf haben.

Um den Ruby-Filter zu verwenden, definieren Sie einen ruby -Filter im Filterabschnitt Ihrer Logstash-Pipeline-Konfigurationsdatei (*.conf). Hier ein einfaches Beispiel:

filter { ruby { code => " event.set('new_field', 'Hello from Ruby!') " } }

Dieser Inline-Ruby-Filter definiert eine Ruby-Filterinstanz innerhalb Ihrer Logstash-Konfiguration. Der Parameter code stellt das Inline-Ruby-Skript bereit, das Logstash für jedes von diesem Filter verarbeitete Ereignis ausführt. Innerhalb dieses Skripts gibt es eine event Variable, die das Ereignis selbst repräsentiert. Das Ereignisobjekt enthält die Originaldaten, die an Logstash gesendet wurden, sowie alle zusätzlichen Felder, die während der Filterphasen von Logstash erstellt wurden. Sie können auf diese Felder über die Logstash Event API zugreifen, zum Beispiel über event.get() und event.set(). In diesem Beispielcode hat event.set('new_field', 'Hello from Ruby!') ein neues Feld mit dem Namen new_field auf den Zeichenkettenwert Hello from Ruby! gesetzt. Sie können bei Bedarf weiteren Code in diesen code -Block einfügen.

Beachten Sie, dass dieses event -Objekt kein gewöhnliches Ruby-Hash-Objekt ist, obwohl es als Datencontainer vom Typ Schlüssel-Wert fungiert. In dieser offiziellen Dokumentation erfahren Sie mehr über die Event-API.

Ruby-Skript auslagern

Für einfache Transformationen ist Inline-Ruby-Code praktisch. Für komplexe Logik oder wiederverwendbare Funktionen empfiehlt es sich jedoch, den Code in ein externes Ruby-Skript auszulagern. Dies verbessert die Wartbarkeit und sorgt für eine saubere Logstash-Pipeline-Konfiguration.

Zuerst erstellen Sie ein Ruby-Skript und speichern es unter dem Namen my_ruby_script.rb. Das Skript muss eine filter Methode definieren, die das Ereignis verarbeitet. Es benötigt ein Ereignisobjekt als Argument, das das aktuell verarbeitete Ereignis repräsentiert. Die Methode filter muss ein Array von Ereignissen zurückgeben, die ausgelöst werden sollen. Um das Ereignis zu verwerfen, geben Sie ein leeres Array zurück.

Das folgende Skript liest beispielsweise das Feld message , berechnet seine Länge und speichert das Ergebnis in einem neuen Feld namens message_length.

def register(params) # This method is called when the plugin is loaded. # You can use it to initialize any instance variables or perform setup tasks. end def filter(event) message = event.get('message') if message event.set('message_length', message.length) end return [event] end

Als Nächstes muss die Ruby-Filterkonfiguration so eingestellt werden, dass sie mit der Option path auf das Skript verweist. Dies weist Logstash an, das externe Skript zu laden und auszuführen. Bei der Verwendung externer Skripte muss sichergestellt werden, dass die Datei existiert und über die korrekten Berechtigungen verfügt.

filter { ruby { path => "/path/to/my_ruby_script.rb" } }

Nun wird jedes Ereignis an die Methode filter in my_ruby_script.rb übergeben und von dieser verarbeitet.

Dieser Ansatz hilft Ihnen, komplexe Logik effektiver zu handhaben und erleichtert so das Testen, Debuggen und Wiederverwenden Ihres Ruby-Codes.

Erweiterte Nutzung

In diesem Abschnitt werden wir einige fortgeschrittene Beispiele für die Verwendung des Ruby-Filters in Logstash untersuchen. Anhand dieser Beispiele wird demonstriert, wie man Datentransformationen durchführt, Ereignisse anreichert und benutzerdefinierte Logik mit Ruby implementiert.

Manipulation verschachtelter Datenstrukturen

Ein Logstash-Ereignis ist die zentrale Datenstruktur, die von Logstash verarbeitet wird. Es kann verschiedene Felder enthalten, darunter auch verschachtelte Datenstrukturen wie Arrays und Hashes. Der Ruby-Filter ermöglicht Ihnen die einfache Bearbeitung dieser verschachtelten Strukturen.

Der Ruby-Filter kann verschachtelte Datenstrukturen wie Hashes und Arrays verarbeiten und ermöglicht es Ihnen, Felder innerhalb dieser Strukturen zu ändern oder hinzuzufügen. Dies ist hilfreich beim Umgang mit komplexen Datenformaten wie JSON.

input { generator { lines => [ '{"nested": {"key1": "value1", "key2": "value2"}}' ] count => 1 codec => "json" ecs_compatibility => "disabled" } } filter { ruby { code => " nested_data = event.get('nested') if nested_data.is_a?(Hash) nested_data['key3'] = 'value3' event.set('nested', nested_data) end " } } output { stdout { codec => rubydebug } }

Dieses Beispiel enthält ein verschachteltes JSON-Objekt in den Eingabedaten. Der Ruby-Filter modifiziert die verschachtelten Daten, indem er ein neues Schlüssel-Wert-Paar hinzufügt. Diese Art der Manipulation von verschachtelten Daten ist mit den Standard-Logstash-Filtern nicht möglich, wodurch der Ruby-Filter eine praktische Option für komplexe Datenstrukturen darstellt.

Teile ein einzelnes Ereignis in mehrere Ereignisse auf

Ruby-Filter können auch verwendet werden, um ein einzelnes Ereignis in mehrere Ereignisse aufzuteilen. Dies ist nützlich, wenn Sie ein einzelnes Ereignis haben, das ein Array von Elementen enthält, und Sie für jedes Element ein separates Ereignis erstellen möchten.

Beachten Sie, dass weder die Ingest-Pipeline von Elasticsearch noch die Prozessoren von Beats/Elastic Agent das Aufteilen von Ereignissen unterstützen. Dies ist einer der überzeugendsten Anwendungsfälle für Logstash.

Mit geteiltem Filter

Mit dem Filter split können Sie ein Ereignis anhand eines bestimmten Feldes in mehrere Ereignisse aufteilen. Wenn Sie jedoch während der Aufteilung zusätzliche Transformationen oder Logik durchführen müssen, können Sie den Ruby-Filter in Kombination mit dem Split-Filter verwenden.

Im folgenden Beispiel haben wir einen RSS-Feed als einzeiligen XML-Text. Es enthält mehrere -Elemente. Der Ruby-Filter dient dazu, die -Elemente aus dem XML zu extrahieren und in einem neuen Feld namens items zu speichern. Anschließend wird der Split-Filter verwendet, um das Ereignis anhand des Feldes items in mehrere Ereignisse aufzuteilen.

input { generator { lines => [ 'Sample RSSArticle 1http://example.com/1Desc 1Article 2http://example.com/2Desc 2' ] count => 1 codec => "plain" ecs_compatibility => "disabled" } } filter { xml { source => "message" target => "rss" store_xml => true force_array => false } ruby { code => "event.set('items', event.get('[rss][channel][item]')) if event.get('[rss][channel][item]')" } split { field => "items" } ruby { code => " item = event.get('items') event.set('title', item['title']) if item['title'] event.set('link', item['link']) if item['link'] event.set('description', item['description']) if item['description'] " } mutate { remove_field => ["@timestamp", "@version", "sequence", "host", "event", "message", "rss", "items"] } } output { stdout { codec => rubydebug } }

Die Ausgabe lautet wie folgt:

{ "title" => "Article 1", "link" => "http://example.com/1", "description" => "Desc 1" } { "title" => "Article 2", "link" => "http://example.com/2", "description" => "Desc 2" }

Wie Sie vielleicht bemerkt haben, ist der ruby -Filter in diesem Fall nicht unbedingt erforderlich. Mit dem Filter split kann das Ereignis anhand des Feldes items in mehrere Ereignisse aufgeteilt werden, und mit dem Filter mutate können unnötige Felder entfernt werden. Wenn Sie jedoch während der Aufteilung zusätzliche Transformationen oder Logik durchführen müssen, können Sie den Ruby-Filter verwenden.

Verwenden Sie das Inline-Ruby-Skript.

Sie können auch ein Inline-Ruby-Skript verwenden, um ein einzelnes Ereignis in mehrere Ereignisse aufzuteilen, indem Sie die Methode event.clone und die Methode new_event_block variable verwenden, z. B. new_event_block.call(new_event). Dies ermöglicht es Ihnen, neue Ereignisse auf Basis des ursprünglichen Ereignisses zu erstellen und dabei dessen Daten zu erhalten.

Hier ist ein Beispiel, wie man den Ruby-Filter verwendet, um ein einzelnes Ereignis in mehrere Ereignisse aufzuteilen. Eingabe und Ausgabe sind die gleichen wie im vorherigen Beispiel.

filter { xml { source => "message" target => "rss" store_xml => true force_array => false } ruby { code => " items = event.get('[rss][channel][item]') if items.is_a?(Array) items.each do |item| new_event = event.clone new_event.set('title', item['title']) new_event.set('link', item['link']) new_event.set('description', item['description']) new_event_block.call new_event end event.cancel elsif items.is_a?(Hash) event.set('title', items['title']) event.set('link', items['link']) event.set('description', items['description']) end " } mutate { remove_field => ["@timestamp", "@version", "sequence", "host", "event", "message", "rss", "items"] } }

Externes Ruby-Skript verwenden

Alternativ können Sie ein externes Ruby-Skript verwenden, um ein einzelnes Ereignis in mehrere Ereignisse aufzuteilen.

Konfigurationsdatei:

filter { xml { source => "message" target => "rss" store_xml => true force_array => false } ruby { path => "path/to/ruby/split_event.rb" } mutate { remove_field => ["@timestamp", "@version", "sequence", "host", "event", "message", "rss", "items"] } }

Das Ruby-Skript muss als split_event.rb externalisiert werden:

def filter(event) items = event.get('[rss][channel][item]') events = [] if items.is_a?(Array) items.each do |item| new_event = event.clone new_event.set('title', item['title']) new_event.set('link', item['link']) new_event.set('description', item['description']) events << new_event end return events elsif items.is_a?(Hash) event.set('title', items['title']) event.set('link', items['link']) event.set('description', items['description']) return [event] else return [] end end

Denken Sie daran, dass die Methode filter ein Array von Ereignissen zurückgeben muss. Sie können mehrere Ereignisse zurückgeben, indem Sie ein eingehendes Ereignisobjekt klonen und die Ergebnisse dem Array hinzufügen, oder Sie können ein einzelnes Ereignis als Array mit einem Element zurückgeben.

return events # or # return [event]

Dies ermöglicht es Ihnen, ein einzelnes Ereignis in mehrere Ereignisse aufzuteilen.

Führe externe Befehle aus und analysiere deren Ausgabe.

Das Logstash exec input-Plugin ermöglicht die Ausführung externer Befehle, deren Ausgabe ein Logstash-Ereignis darstellt. Die Ausgabe des Befehls wird im Feld message des Ereignisses gespeichert.

Normalerweise sind die Ausgaben von Systembefehlen für Menschen lesbar, aber nicht als JSON oder in anderen Formaten strukturiert, die Logstash problemlos parsen kann. Um dies zu handhaben, können Sie den Ruby-Filter verwenden, um die Ausgabe zu analysieren und die Informationen daraus zu extrahieren.

Hier ist ein Beispiel für die Verwendung des exec -Input-Plugins zur Ausführung des ps -ef -Befehls, der alle laufenden Prozesse auf einem Unix-ähnlichen System auflistet. Die Ausgabe wird vom Ruby-Filter analysiert, um relevante Informationen über jeden Prozess zu extrahieren.

input { exec { command => "ps -ef" interval => 60 } } filter { ruby { code => ' processes = [] lines = event.get("message").split("\n") lines.each_with_index do |line, index| # Skip header line and empty lines next if index == 0 || line.strip.empty? entry = nil # Use regex to match the ps -ef output format more flexibly # This pattern accounts for variable spacing and different time formats if line =~ /^\s*(\S+)\s+(\d+)\s+(\d+)\s+(\d+)\s+(\S+)\s+(\S+)\s+([\d:]+\.?\d*)\s+(.+)$/ uid, pid, ppid, c, stime, tty, time, cmd = $1, $2, $3, $4, $5, $6, $7, $8 entry = { "UID" => uid, "PID" => pid, "PPID" => ppid, "C" => c, "STIME" => stime, "TTY" => tty, "TIME" => time, "CMD" => cmd.strip } elsif line =~ /^\s*(\S+)\s+(\d+)\s+(\d+)\s+(\d+)\s+(.+)$/ # Fallback pattern for lines that might not match the exact format # Split the remaining part more carefully uid, pid, ppid, c, remainder = $1, $2, $3, $4, $5 # Split remainder into STIME, TTY, TIME, CMD parts = remainder.strip.split(/\s+/, 4) if parts.length >= 4 stime, tty, time, cmd = parts[0], parts[1], parts[2], parts[3] entry = { "UID" => uid, "PID" => pid, "PPID" => ppid, "C" => c, "STIME" => stime, "TTY" => tty, "TIME" => time, "CMD" => cmd } end end if entry && entry["UID"] == "0" original_line = line.strip entry["original_line"] = original_line if original_line.length > 0 processes.push(entry) end end event.set("processes", processes) event.remove("message") event.remove("event") ' } } output { stdout { codec => rubydebug } }

Dieses Beispiel verwendet das exec -Input-Plugin, um den ps -ef -Befehl alle 60 Sekunden auszuführen. Der Ruby-Filter verarbeitet die Ausgabe und extrahiert relevante Felder wie UID, PID, PPID, CPU-Auslastung (C), Startzeit (STIME), TTY, Gesamt-CPU-Zeit (TIME) und den ausgeführten Befehl (CMD). Auf meiner macOS-Umgebung funktioniert es einwandfrei, aber möglicherweise müssen Sie die Regex-Muster an das Ausgabeformat des Befehls ps -ef auf Ihrem System anpassen.

Verwenden Sie integrierte Bibliotheken

Das Ruby-Filter-Plugin ermöglicht die Verwendung integrierter Ruby-Bibliotheken, was für verschiedene Aufgaben sehr nützlich sein kann. Beispielsweise können Sie die json -Bibliothek zum Parsen von JSON-Zeichenketten oder die date -Bibliothek zum Bearbeiten von Datumsangaben verwenden.

Hier ist ein Beispiel für die Verwendung der json -Bibliothek zum Parsen einer in einem Feld gespeicherten JSON-Zeichenkette:

require 'json' def filter(event) json_string = event.get('message') parsed_json = JSON.parse(json_string) event.set('parsed_json', parsed_json) return [event] end

Um zu vermeiden, dass die Bibliothek jedes Mal neu geladen werden muss, sollten Sie Ihren Ruby-Code auslagern, damit Sie die require -Anweisung am Anfang Ihres Ruby-Filterskripts verwenden können. Dadurch wird die Bibliothek einmalig geladen und steht Ihnen anschließend in Ihrem Skript zur Verfügung.

Um zu überprüfen, welche Bibliotheken in Ihrer Umgebung verfügbar sind, können Sie die integrierten Bibliotheken auflisten, indem Sie den folgenden Code im Ruby-Filter ausführen:

Gem.loaded_specs.sort_by { |name, _| name }.each do |name, spec| puts "#{name}: #{spec.version}" end

Hinweis: Die integrierten Bibliotheken werden von Logstash nicht offiziell unterstützt, und ihr Verhalten kann sich ändern oder sie sind in zukünftigen Versionen möglicherweise nicht mehr verfügbar. Die Benutzung erfolgt auf eigene Gefahr.

Fazit

Mit dem Logstash Ruby-Filter können Sie die Funktionen Ihrer Logstash-Pipelines anpassen und erweitern. In diesem Beitrag haben wir die Grundlagen der Verwendung des Ruby-Filters behandelt und fortgeschrittene Anwendungsbeispiele vorgestellt.

Durch die Nutzung des Ruby-Filters können Sie komplexe Datenverarbeitungsaufgaben bewältigen, die benutzerdefinierte Logik oder fortgeschrittene Manipulationen erfordern. Egal ob Sie mit verschachtelten Datenstrukturen arbeiten, Ereignisse aufteilen oder komplexen/unstrukturierten Text in strukturiertes JSON parsen und konvertieren, der Ruby-Filter bietet die Flexibilität, Ihre spezifischen Anforderungen zu erfüllen.

Wir hoffen, dass Ihnen dieser Leitfaden das Wissen und die Inspiration vermittelt hat, das volle Potenzial des Logstash Ruby-Filters auszuschöpfen. Viel Spaß beim Skripten!

Dai Sugimori - Elasticsearch Labs