Ruby - Elasticsearch Labs

Einführung des ES|QL-Abfragegenerators für den Elasticsearch Ruby Client

Fernando Briano — Wed, 17 Sep 2025 00:00:00 GMT

Wir haben kürzlich elastic-esql veröffentlicht, ein Ruby-Gem, das unter der Apache 2-Lizenz veröffentlicht wurde. Dieses Juwel ermöglicht es Ihnen, Elastic ES|QL- Abfragen in idiomatischem Ruby zu erstellen, die Sie dann mit der ES|QL-Abfrage-API verwenden können. ES|QL ermöglicht es Entwicklern, in Elasticsearch gespeicherte Daten mittels Abfragen zu filtern, zu transformieren und zu analysieren. Es verwendet "Pipes" ( | ), um die Daten schrittweise zu verarbeiten. Das Gem verwendet stattdessen Ruby-Funktionen, die Sie an das ursprüngliche Objekt anhängen können, um komplexere Abfragen zu erstellen:

ESQL:

Rubin:

Elastic::ESQL.from('sample_data').limit(2).sort('@timestamp').descending

Installation

Das Gem kann über RubyGems installiert werden mit:

gem install elastic-esql

Alternativ kann es der Gemfile-Datei eines Projekts hinzugefügt werden:

gem 'elastic-esql'

Verwendung

Sie können entweder eine vollständige Abfrage auf einmal erstellen oder ein Abfrageobjekt mit einem Quellbefehl wie from oder row erstellen und dann ES|QL-Methoden verketten, um darauf aufzubauen.

query = Elastic::ESQL.from('sample_data') query.limit(2).sort('@timestamp')

Das Gem übersetzt den Code in ES|QL für die to_s -Methode, sodass es die ES|QL-Abfrage zurückgibt, wenn sie ausgegeben oder als String gecastet wird:

query = Elastic::ESQL.from('sample_data').limit(2).sort('@timestamp').descending query.to_s # => "FROM sample_data | LIMIT 2 | SORT @timestamp DESC"

Sie können ein Abfrageobjekt instanziieren und seinen Anfangszustand verändern, indem Sie die ! -Äquivalente jeder Funktion verwenden:

query = Elastic::ESQL.from('sample_data') query.to_s # => "FROM sample_data" query.limit!(2).sort!('@timestamp') query.to_s # => "FROM sample_data | LIMIT 2 | SORT @timestamp"

Das Tool bietet bequeme Möglichkeiten, zusätzliche Schritte an eine ES|QL-Funktion anzuhängen, wie z. B. enrich und sort. Sobald Sie enrich auf einem Elastic::ESQL -Objekt aufgerufen haben, können Sie on und with daran anhängen:

esql.enrich!('policy').on('a').with({ name: 'language_name' })

Sie können auch desc, asc, nulls_first und nulls_last an Ihre Abfrage anhängen, nachdem Sie sort verwendet haben:

Elastic::ESQL.from('sample_data').sort('@timestamp').asc.to_s # => 'FROM sample_data | SORT @timestamp ASC' Elastic::ESQL.from('sample_data').sort('@timestamp').desc.nulls_first.to_s # => 'FROM sample_data | SORT @timestamp DESC NULLS FIRST'

Es unterstützt auch benutzerdefinierte Zeichenketten, falls Sie die ES|QL-Abfrage selbst schreiben oder eine Funktion nutzen möchten, die noch nicht in die Bibliothek aufgenommen wurde. custom wird die Zeichenketten am Ende der Abfrage zusammenfügen. Die Zeichen werden beim Senden an die Funktion hinzugefügt, ohne dabei Pipe-Zeichen einzufügen. Sie werden durch ein Leerzeichen mit dem Rest der Anfrage verbunden.

esql = Elastic::ESQL.from('sample_data') esql.custom('| MY_VALUE = "test value"').to_s # => 'FROM sample_data | MY_VALUE = "test value"'

Sie können auch custom -Funktionen verketten:

esql.custom('| MY_VALUE = "test value"').custom('| ANOTHER, VALUE') 'FROM sample_data | MY_VALUE = "test value" | ANOTHER, VALUE'

Verwendung des ES|QL Query Builders mit dem Ruby-Client

Sie können den Query Builder direkt mit elasticsearch-ruby und der esql.query API verwenden, indem Sie das Query-Objekt senden:

require 'elasticsearch' require 'elastic/esql' client = Elasticsearch::Client.new index = 'sample_data' query = Elastic::ESQL.from(index) .sort('@timestamp') .desc .where('event_duration > 5000000') .limit(3) .eval({ duration_ms: 'ROUND(event_duration/1000000.0, 1)' }) client.esql.query(body: { query: query })

Sie können es auch mit dem ES|QL-Helper des Elasticsearch Ruby-Clients verwenden. Weitere Informationen finden Sie hier:

require 'elasticsearch/helpers/esql_helper' Elasticsearch::Helpers::ESQLHelper.query(client, query)

Als eigenständiges Werkzeug

Das Gem ist als eigenständiges Werkzeug konzipiert, um ES|QL-Abfragen auf idiomatische Weise zu erstellen. Es hat keine Laufzeitabhängigkeiten; Sie können es mit dem offiziellen Elasticsearch Ruby-Client oder auch eigenständig verwenden.

Die generierte Abfrage kann mit der esql.query API auf jede Art und Weise verwendet werden, wie eine Anwendung mit der Elasticsearch API interagiert (Ruby oder nicht). Sobald eine Abfrage mit elastic-esql erstellt wurde, kann die generierte Zeichenkette als Parameter query im Anfragetext an die API gesendet werden.

Ich habe bereits über die Verwendung von Elasticsearch mit gängigen Ruby-Tools geschrieben. Dieses Gem kann mit allen gängigen Ruby-Tools verwendet werden, um Elasticsearch mit ES|QL abzufragen.

Fazit

Diese Bibliothek befindet sich in aktiver Entwicklung, und die endgültige API ist noch nicht fertiggestellt. Es ist aktuell als technische Vorschauversion veröffentlicht. Sollten Sie Feedback zur aktuellen API oder zur allgemeinen Nutzung haben, zögern Sie bitte nicht , ein neues Issue zu eröffnen. Weitere Informationen zum Ruby ES|QL Query Builder finden Sie in der README-Datei .

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!

Wie Sie Ihre Ruby-Anwendung von OpenSearch zu Elasticsearch migrieren

Fernando Briano — Fri, 13 Dec 2024 00:00:00 GMT

Der OpenSearch Ruby-Client wurde in Version 7.x vom Elasticsearch Ruby-Client abgeleitet, daher sind die Codebasen relativ ähnlich. Das bedeutet, dass beim Migrieren einer Ruby-Codebasis von OpenSearch zu Elasticsearch der Code aus den jeweiligen Clientbibliotheken sehr vertraut aussehen wird. In diesem Blogbeitrag zeige ich eine Beispiel-Ruby-Anwendung, die OpenSearch verwendet, und die Schritte zur Migration dieses Codes zu Elasticsearch.

Beide Clients werden unter der weit verbreiteten Apache-Lizenz 2.0 veröffentlicht und sind somit Open Source und freie Software. Die Lizenz von Elasticsearch wurde kürzlich aktualisiert, und der Kern von Elasticsearch und Kibana wird seit Version 8.16 unter der von der OSI genehmigten Open-Source-Lizenz AGPL veröffentlicht.

Bei der Migration einer Ruby-Anwendung die Elasticsearch-Version berücksichtigen

Bei der Migration ist es unter anderem zu berücksichtigen, welche Version von Elasticsearch verwendet werden soll. Wir empfehlen die Verwendung der neuesten stabilen Version, die zum Zeitpunkt der Erstellung dieses Dokuments 8.17.0 ist. Die Nebenversionen des Elasticsearch Ruby Clients orientieren sich an den Nebenversionen von Elasticsearch. Für Elasticsearch 8.17.x können Sie also Version 8.17.x des Ruby-Gems verwenden.

OpenSearch ist ein Fork von Elasticsearch 7.10.2. Daher können sich die APIs geändert haben und es können unterschiedliche Funktionen auf beiden Plattformen genutzt werden. Das würde jedoch den Rahmen dieses Beitrags sprengen, und ich werde mich daher nur mit den häufigsten Operationen in einer Beispielanwendung befassen.

Für Ruby on Rails können Sie den offiziellen Elasticsearch-Client oder die Rails-Integrationsbibliotheken verwenden. Wir empfehlen, auf die jeweils neueste stabile Version von Elasticsearch und des Clients zu migrieren. Die Gem-Version elasticsearch-rails 8.0.0 unterstützt Rails 6.1, 7.0 und 7.1 sowie Elasticsearch 8.x.

Der Code

In diesem Beispiel bin ich den Schritten zur Installation von OpenSearch aus einem Tarball gefolgt. Nach dem Herunterladen und Entpacken des Tarballs musste ich ein anfängliches Administratorpasswort festlegen, das ich später zur Instanziierung des Clients verwenden werde.

Ich habe ein Verzeichnis mit Gemfile erstellt, das folgendermaßen aussieht:

source 'https://rubygems.org' gem 'opensearch-ruby'

Nach dem Ausführen von bundle install ist das Gem für mein Projekt installiert. Es wurde opensearch-ruby Version 3.4.0 installiert, und die Version von OpenSearch, die ich verwende, ist 2.18.0. Ich habe den Code in einer example_code.rb -Datei im selben Verzeichnis geschrieben. Der initiale Code in dieser Datei ist die Instanziierung eines OpenSearch-Clients:

require 'opensearch' client = OpenSearch::Client.new( host: 'https://localhost:9200', user: 'admin', password: ENV['OPENSEARCH_INITIAL_ADMIN_PASSWORD'], transport_options: { ssl: { verify: false } } )

Der Parameter „Transportoption ssl: { verify: false} wird gemäß Benutzerhandbuch übergeben, um das Testen zu vereinfachen. Im Produktionsbetrieb sollte dies je nach Bereitstellung von OpenSearch konfiguriert werden.

Seit Version 2.12.0 von OpenSearch muss die Umgebungsvariable OPENSEARCH_INITIAL_ADMIN_PASSWORD beim Ausführen des Installationsskripts auf ein sicheres Passwort gesetzt werden. Nachdem ich die Schritte zur Installation von OpenSearch aus einem Tarball befolgt hatte, exportierte ich die Variable in meiner Konsole und sie steht nun meinem Ruby-Skript zur Verfügung.

Eine einfache API, um sicherzustellen, dass der Client eine Verbindung zu OpenSearch herstellt, verwendet die cluster.health API:

puts 'HEALTH:' pp client.cluster.health

Und es funktioniert tatsächlich:

$ be ruby example_code.rb HEALTH: {"cluster_name"=>"opensearch", "status"=>"yellow", "timed_out"=>false, "number_of_nodes"=>1, "number_of_data_nodes"=>1,

Ich habe einige der gängigen Beispiele aus der Elasticsearch Ruby-Client-Dokumentation getestet, und sie funktionieren wie erwartet:

index = 'books' puts 'Creating index' response = client.indices.create(index: index) puts response # Creating index # {"acknowledged"=>true, "shards_acknowledged"=>true, "index"=>"books"} puts 'Indexing a document' document = { title: 'The Time Machine', author: 'H. G. Wells', year: 1895 } response = client.index(index: index, body: document, refresh: true) puts response # Indexing document # {"_index"=>"books", "_id"=>"esalT5MB4vnuJz5TtqOc", "_version"=>1, "result"=>"created", "forced_refresh"=>true, "_shards"=>{"total"=>2, "successful"=>1, "failed"=>0}, "_seq_no"=>0, "_primary_term"=>1} id = response['_id'] puts 'Getting document' response = client.get(index: index, id: id) puts response # Getting document # {"_index"=>"books", "_id"=>"esalT5MB4vnuJz5TtqOc", "_version"=>1, "_seq_no"=>0, "_primary_term"=>1, "found"=>true, "_source"=>{"title"= >"The Time Machine", "author"=>"H. G. Wells", "year"=>1895}} puts "Does an index exist?" puts client.indices.exists(index: 'imaginary_index') # Does an index exist? # false puts 'Processing Bulk request' body = [ { index: { _index: 'books', data: { name: 'Leviathan Wakes', author: 'James S.A. Corey', release_date: '2011-06-02', page_count: 561 } } }, { index: { _index: 'books', data: { name: 'Hyperion', author: 'Dan Simmons', release_date: '1989-05-26', page_count: 482 } } }, { index: { _index: 'books', data: { name: 'Dune', author: 'Frank Herbert', release_date: '1965-06-01', page_count: 604 } } }, { index: { _index: 'books', data: { name: 'Dune Messiah', author: 'Frank Herbert', release_date: '1969-10-15', page_count: 331 } } }, { index: { _index: 'books', data: { name: 'Children of Dune', author: 'Frank Herbert', release_date: '1976-04-21', page_count: 408 } } }, { index: { _index: 'books', data: { name: 'God Emperor of Dune', author: 'Frank Herbert', release_date: '1981-05-28', page_count: 454 } } }, { index: { _index: 'books', data: { name: 'Consider Phlebas', author: 'Iain M. Banks', release_date: '1987-04-23', page_count: 471 } } }, { index: { _index: 'books', data: { name: 'Pandora\'s Star', author: 'Peter F. Hamilton', release_date: '2004-03-02', page_count: 768 } } }, { index: { _index: 'books', data: { name: 'Revelation Space', author: 'Alastair Reynolds', release_date: '2000-03-15', page_count: 585 } } }, { index: { _index: 'books', data: { name: 'A Fire Upon the Deep', author: 'Vernor Vinge', release_date: '1992-06-01', page_count: 613 } } }, { index: { _index: 'books', data: { name: 'Ender\'s Game', author: 'Orson Scott Card', release_date: '1985-06-01', page_count: 324 } } }, { index: { _index: 'books', data: { name: '1984', author: 'George Orwell', release_date: '1985-06-01', page_count: 328 } } }, { index: { _index: 'books', data: { name: 'Fahrenheit 451', author: 'Ray Bradbury', release_date: '1953-10-15', page_count: 227 } } }, { index: { _index: 'books', data: { name: 'Brave New World', author: 'Aldous Huxley', release_date: '1932-06-01', page_count: 268 } } }, { index: { _index: 'books', data: { name: 'Foundation', author: 'Isaac Asimov', release_date: '1951-06-01', page_count: 224 } } }, { index: { _index: 'books', data: { name: 'The Giver', author: 'Lois Lowry', release_date: '1993-04-26', page_count: 208 } } }, { index: { _index: 'books', data: { name: 'Slaughterhouse-Five', author: 'Kurt Vonnegut', release_date: '1969-06-01', page_count: 275 } } }, { index: { _index: 'books', data: { name: 'The Hitchhiker\'s Guide to the Galaxy', author: 'Douglas Adams', release_date: '1979-10-12', page_count: 180 } } }, { index: { _index: 'books', data: { name: 'Snow Crash', author: 'Neal Stephenson', release_date: '1992-06-01', page_count: 470 } } }, { index: { _index: 'books', data: { name: 'Neuromancer', author: 'William Gibson', release_date: '1984-07-01', page_count: 271 } } }, { index: { _index: 'books', data: { name: 'The Handmaid\'s Tale', author: 'Margaret Atwood', release_date: '1985-06-01', page_count: 311 } } }, { index: { _index: 'books', data: { name: 'Starship Troopers', author: 'Robert A. Heinlein', release_date: '1959-12-01', page_count: 335 } } }, { index: { _index: 'books', data: { name: 'The Left Hand of Darkness', author: 'Ursula K. Le Guin', release_date: '1969-06-01', page_count: 304 } } }, { index: { _index: 'books', data: { name: 'The Moon is a Harsh Mistress', author: 'Robert A. Heinlein', release_date: '1966-04-01', page_count: 288 } } } ] puts client.bulk(body: body, refresh: true) # Processing Bulk request # {"took"=>38, "errors"=>false, "items"=>[{"index"=>{"_index"=>"books", "_id"=>" ... query = { query: { multi_match: { query: 'dune', fields: ['name'] } } } puts 'Search results' response = client.search(index: index, body: query) puts response # Search results # {"_index"=>"books", "_id"=>"oEawT5MBOXHuGXdEu5Wu", "_score"=>2.2886353, "_source"=>{"name"=>"Dune", "author"=>"Frank Herbert", "release_date"=>"1965-06-01", "page_count"=>604}} # {"_index"=>"books", "_id"=>"oUawT5MBOXHuGXdEu5Wu", "_score"=>1.8893257, "_source"=>{"name"=>"Dune Messiah", "author"=>"Frank Herbert", "release_date"=>"1969-10-15", "page_count"=>331}} # {"_index"=>"books", "_id"=>"okawT5MBOXHuGXdEu5Wu", "_score"=>1.6086557, "_source"=>{"name"=>"Children of Dune", "author"=>"Frank Herbert", "release_date"=>"1976-04-21", "page_count"=>408}} # {"_index"=>"books", "_id"=>"o0awT5MBOXHuGXdEu5Wu", "_score"=>1.40059, "_source"=>{"name"=>"God Emperor of Dune", "author"=>"Frank Herbert", "release_date"=>"1981-05-28", "page_count"=>454}} puts 'Updating document' document = { title: 'Walkaway', author: 'Cory Doctorow', release_date: '2017' } response = client.index(index: index, body: document, refresh: true) id = response['_id'] response = client.update(index: index, id: id, body: { doc: { release_date: '2017-04-26' } }) puts response # Updating document # {"_index"=>"books", "_id"=>"degnZJMBIGr4X0Yim55L", "_version"=>2, "result"=>"updated", "_shards"=>{"total"=>2, "successful"=>1, "failed"=>0}, "_seq_no"=>26, "_primary_term"=>1} puts 'Retrieveing multiple documents' response = client.search(index: index, body: { query: { match_all: {} }, size: 3, stored_fields: '_id' }) ids = response['hits']['hits'] ids.map { |a| a.delete('_score') } response = client.mget(body: { docs: [{ _index: index, _id: ids }] }) puts response # Retrieveing multiple documents # {"docs"=>[{"_index"=>"books", "_id"=>"qeg2ZJMBIGr4X0YiiqD2", "_version"=>1, "_seq_no"=>0, "_primary_term"=>1, "found"=>true, "_source"=>{"title"=>"The Time Machine", "author"=>"H. G. Wells", "year"=>1895}}, {"_index"=>"books", "_id"=>"q-g2ZJMBIGr4X0Yii6Ah", "_version"=>1, "_seq_no"=>1, "_primary_term"=>1, "found"=>true, "_source"=>{"name"=>"Leviathan Wakes", "author"=>"James S.A. Corey", "release_date"=>"2011-06-02", "page_count"=>561}}, {"_index"=>"books", "_id"=>"rOg2ZJMBIGr4X0Yii6Ah", "_version"=>1, "_seq_no"=>2, "_primary_term"=>1, "found"=>true, "_source"=>{"name"=>"Hyperion", "author"=>"Dan Simmons", "release_date"=>"1989-05-26", "page_count"=>482}}]} puts "Count #{client.count(index: index)['count']}" puts 'Deleting by query' response = client.delete_by_query(index: index, body: { query: { match: { author: 'Robert A. Heinlein' } } }, refresh: true) puts response puts "Count #{client.count(index: index)['count']}" # Count 26 # Deleting by query # {"took"=>16, "timed_out"=>false, "total"=>2, "deleted"=>2, "batches"=>1, "version_conflicts"=>0, "noops"=>0, "retries"=>{"bulk"=>0, "search"=>0}, "throttled_millis"=>0, "requests_per_second"=>-1.0, "throttled_until_millis"=>0, "failures"=>[]} # Count 24 puts 'Deleting document' response = client.delete(index: index, id: id) puts response # Deleting document # {"_index"=>"books", "_id"=>"nEawT5MBOXHuGXdEu5WA", "_version"=>2, "result"=>"deleted", "_shards"=>{"total"=>2, "successful"=>1, "failed"=>0}, "_seq_no"=>25, "_primary_term"=>1} puts 'Deleting index' response = client.indices.delete(index: index) puts response # Deleting index # {"acknowledged"=>true}

Migration einer Ruby-Anwendung zu Elasticsearch

Der erste Schritt besteht darin, elasticsearch-ruby in die Gemfile einzufügen. Nach dem Ausführen von bundle install wird das Elasticsearch Ruby Client Gem installiert. Wenn Sie Ihren Code vor der vollständigen Migration testen möchten, können Sie das opensearch-ruby Gem zunächst dort belassen.

Der nächste wichtige Schritt wird die Client-Instanziierung sein. Das hängt davon ab, wie Sie Elasticsearch betreiben. Um bei diesen Beispielen eine ähnliche Vorgehensweise beizubehalten, folge ich den Schritten unter Elasticsearch herunterladen und lokal ausführen.

Beim Ausführen von bin/elasticsearch startet Elasticsearch mit automatisch konfigurierten Sicherheitsfunktionen. Stellen Sie sicher, dass Sie das Passwort für den Elastic-Benutzer kopieren (Sie können es aber durch Ausführen bin/elasticsearch-reset-password -u elastic zurücksetzen). Wenn Sie diesem Beispiel folgen, stellen Sie sicher, dass Sie OpenSearch beenden, bevor Sie Elasticsearch starten, da beide auf demselben Port laufen.

Am Anfang von example_code.rb habe ich die OpenSearch-Client-Instanziierung auskommentiert und die Instanziierung für einen Elasticsearch-Client hinzugefügt:

# require 'opensearch' # client = OpenSearch::Client.new( # host: 'https://localhost:9200', # user: 'admin', # password: ENV['OPENSEARCH_INITIAL_ADMIN_PASSWORD'] # transport_options: { ssl: { verify: false } } # ) require 'elasticsearch' client = Elasticsearch::Client.new( host: 'https://localhost:9200', user: ENV['ELASTICSEARCH_USER'], password: ENV['ELASTICSEARCH_PASSWORD'], transport_options: { ssl: { verify: false } } )

Wie Sie sehen können, ist der Code in diesem Testszenario nahezu identisch. Dies hängt von der Art der Elasticsearch-Implementierung und der gewählten Verbindungs- und Authentifizierungsmethode ab. Dasselbe gilt hier wie bei OpenSearch in Bezug auf die Sicherheit: Die Option, SSL nicht zu überprüfen, dient nur zu Testzwecken und sollte nicht in der Produktion verwendet werden.

Sobald der Client eingerichtet ist, führe ich den Code erneut aus mit: bundle exec ruby example_code.rb. Und alles funktioniert einfach!

Behebung von Migrationsproblemen

Je nachdem, welche APIs Ihre Anwendung verwendet, besteht die Möglichkeit, dass Sie beim Ausführen Ihres Codes gegen Elasticsearch einen Fehler erhalten, wenn die APIs von OpenSearch voneinander abweichen. Die Dokumentation der REST-APIs ist eine unverzichtbare Referenz für detaillierte Informationen zur Verwendung der APIs. Bitte prüfen Sie die Dokumentation für die Version von Elasticsearch, die Sie verwenden. Sie können auch auf die Referenz Elasticsearch::API verweisen.

Mögliche Fehler bei Elasticsearch sind beispielsweise:

ArgumentError: Required argument '' missing - Dies ist ein Clientfehler, der auftritt, wenn einer Anfrage ein erforderlicher Parameter fehlt.
Elastic::Transport::Transport::Errors::BadRequest: [400] {"error":{"root_cause":[{"type":"illegal_argument_exception","reason":"request [/example/_doc] contains unrecognized parameter: [test]"}]... Dieser Fehler stammt von Elasticsearch und bedeutet, dass der Client-Code einen Parameter verwendet, den Elasticsearch für die verwendete API nicht erkennt.

Der Elasticsearch-Client wird Fehler von Elasticsearch mit der detaillierten Fehlermeldung, die vom Server gesendet wird, melden. Selbst bei nicht unterstützten Parametern oder Endpunkten sollte die Fehlermeldung darüber informieren, was anders ist.

Fazit

Wie wir anhand dieses Beispielcodes gezeigt haben, ist die Migration einer Ruby-Anwendung von OpenSearch zu Elasticsearch von der Ruby-Seite her nicht allzu komplex. Sie müssen sich über die Versionsverwaltung und mögliche Unterschiede in den APIs der Suchmaschinen im Klaren sein. Bei den häufigsten Aktionen besteht die größte Änderung bei der Migration von Clients jedoch in der Instanziierung. In dieser Hinsicht ähneln sie sich beide, aber die Art und Weise, wie Host und Anmeldeinformationen definiert werden, variiert je nachdem, wie der Stack bereitgestellt wird. Sobald der Client eingerichtet ist und Sie überprüft haben, dass er eine Verbindung zu Elasticsearch herstellt, können Sie den OpenSearch-Client nahtlos durch den Elasticsearch-Client ersetzen.