Dokumentation ELK

From swissbib
Jump to: navigation, search

Der ELK-Stack (E = elasticsearch, L = Logstash, K = Kibana) ist die zentrale Toolchain um die Nutzerdaten der swissbib-Plattform zu sammeln, bearbeiten und analysieren. Dieser Software Stack wird von einer Firma entwickelt und wird Open Source zur Verfügung gestellt. Allgemeine Dokumentation findet man auf https://www.elastic.co/de/.

Diese Seite enthält eine spezifische Anleitung zur Nutzung von Kibana und zum Aufbau des elasticsearch Index. Details zu allgemeineren oder spezifischeren Fragen sollen der offiziellen Dokumentation entnommen werden.

Allgemeine Architektur

In der Abbildung sieht man den allgemeinen Weg, welche die Daten nehmen.

Architektur swissbib-ELK 28.09.2018


Wichtig zu wissen dabei: Was aufgezeichnet wird, ist die HTTP-Kommunikation zwischen der Oberfläche und dem Server. Alles was keine Kommunikation auslöst, wird damit auch nicht aufgezeichnet.

Kibana

Discover: Dieser Reiter ist dazu da, um die Daten im Allgemeinen zu untersuchen.

Visualize: In diesem Reiter werden Visualisierungen erstellt. Eine einzelne Visualisierung ist dazu da, um eine gezielte Aussage machen zu können. Im Dashboard kann man diese Aussagen, dann kombinieren.

Dashboard: Für das Zusammenstellen von Visualisierungen auf einem Bildschirm. Hier kommt das Endprodukt zusammen und dient hauptsächlich zur Übersicht über die Zahlen & Analysen. Die Resultate können weiter mit Suchen & Filtern spezialisiert werden.

Timelion: Zum Erstellen von komplexen, temporalen Visualisierungen.

APM: Nicht relevant für uns.

Dev Tools: Direktes Interface zum elasticsearch Index. Hier kann alles gemacht werden, inkl. löschen aller Daten. Bitte nicht benutzen!

Monitoring: Kann den Status des elasticsearch Servers anzeigen.

Management: Verwalten der Einstellungen, erstellter Objekte und der Index Patterns. Bitte keine Veränderungen vornehmen!

Erstellen von Filtern

Wie man einen einfachen Filter erstellt.

Filter werden verwendet, um die angezeigten Dokumente nach einem bestimmten Wert in einem Feld einzugrenzen oder auszuschliessen. Die Werte können einzelne Begriffe, mehrere Begriffe oder Zahlenmengen sein. Mit "exists" ist es auch möglich zu überprüfen, ob ein Feld überhaupt im Dokument vorkommt.

Wenn man mit dem Maus-Curser über den Filter fährt, erscheinen fünf Icons. Mit dem ersten (Häkchen) kann man den Filter aktivieren / deaktivieren. Mit dem zweiten (Stecknadel) kann man den Filter anpinnen, d.h. der Filter bleibt wenn man auf eine andere Ansicht wechselt. Mit der Lupe kann man den Filter in seiner Bedeutung umkehren. Mit dem Abfalleimer kann man den Filter löschen und mit dem Bleistift kann man den Filter bearbeiten. Bei der Erarbeitung kann man auch ein Label setzten, welches dann auf dem Filter angezeigt wird.

Erstellen von Visualisierungen

Wie man eine einfache Visualisierung erstellt.

Eine Visualisierung ist dazu gedacht, einen einfachen Zusammenhang in den Daten darzustellen. Es gibt einige verschiedene Typen von Visualisierungen. Wichtig ist, dass man sich zuerst überlegt, was man am Ende sehen möchte. Anschliessend muss man sich die Daten anschauen und analysieren, ob die Antwort auf diese Frage in den Daten vorhanden ist. Wenn man die Felder, welche zusammengeführt werden müssen, identifiziert hat, sollte man sich überlegen welche Art von Visualisierung am besten dazu geeignet ist.

Die wichtigsten Visualisierungen sind Metric, Data Table, Horizontal / Vertical Bar & Pie.

Die Metric zeigt einfach eine oder mehrere Zahlen an, die über eine beliebige Anzahl Dokumente aggregiert werden. Zum Beispiel wenn man die Summe aller Aufrufe in einem bestimmten Bereich oder einem bestimmten Buch sehen will.

Die Data Table ist eine einfache Tabelle und kann auch als CSV exportiert werden. Vor allem nützlich um die Daten zu erkunden und nicht für Visualisierungen.

Die Bar Charts sind die nützlichsten um Daten über die Zeit oder über verschiedene Werte von einem Feld in einem anderen Feld zu visualisieren. Zum Beispiel die Anzahl Aufrufe pro Tag. Durch das Aufteilen der Bars in Untereinheiten, kann man auch eine dritte Dimension / drittes Feld einfügen.

Das Kuchendiagramm dient in erster Linie dazu, prozentuale Zusammenhänge darzustellen.

Wenn für ein eigenes Dashbord neue Visualisierungen erstellt werden, diese bitte nach dem Muster "Name Dashboard": "Titel der Visualisierung" benennen.


Elasticsearch

Wichtige Begriffe

Begriff Erklärung
Elasticsearch Die Software, die für das Indexieren der Daten zuständig ist und eine Schnittstelle zum Suchen zur Verfügung stellt.
Kibana Eine Software, welche eine Web-Oberfläche für Elasticsearch darstellt und es ermöglicht, mit einem GUI auf den Index zuzugreifen.
Index Der Index ist eine Sammlung von Dokumenten, die in Elasticsearch definiert sind und durchsuchbar sind. Jeder Index kann separat durchsucht werden. In einem Index müssen alle Dokumente vom selben Typ sein, das heisst sie müssen mit dem gleichen Mapping definiert werden.
Mapping Ein Mapping definiert alle Feldnamen und den dazugehörigen Datentyp in einem Dokument. Ein Feld kann anschliessend nur Daten enthalten, welche diesem Typen entsprechen. Nicht alle Felder die in einem Mapping definiert sind, müssen in jedem Dokument vorkommen, aber jedes Feld das vorkommt, muss im Mapping definiert sein. (elasticsearch kann in der Regel sehr gut selbst ein Mapping erstellen, wenn man Daten indexiert.)
Datentypen Die Datentypen definiert in Elasticsearch sind Text, Nummer, IP-Adresse, Object und Zeit/Datum.
Index-Pattern In Kibana kann man sogenannte Index-Pattern definieren, welche es erlauben, in Kibana mehrere Indizes mit einer Suche zu durchsuchen.
Dokument Das Dokument in einem Index ist die kleinste sichtbare, und damit zählbare, Einheit. Jedes Dokument besteht aus verschiedenen Feldern, welche die Daten halten. In unserem Kontext ist das Dokument ein Log-Eintrag.
Feld Jedes Feld hat einen Datentyp, einen Namen und einen oder mehrere Werte. Nach dem Wert kann gesucht werden, je nach dem wie das Feld indexiert ist. Es gibt viele verschiedene Möglichkeiten ein Feld zu indexieren. Am häufigsten indexiert wird als Text. Das heisst, dass jedes Wort indexiert und damit auffindbar wird. Hier werden aber Stopwörter (wie z.B. und, oder, wie etc.) und Sonderzeichen ignoriert und sind damit nicht mehr auffindbar. Die zweite Alternative ist eine Single-Term Indexierung. Hier wird der gesamte Inhalt eines Feldes im Index gespeichert und ist auch nur so auffindbar.
Unterfeld Jedes Feld kann Unterfelder haben. Diese dienen dazu, um bei einem Feld verschiedene Indexierungen vornehmen zu können und damit verschiedene Suchen zu ermöglichen. Das am meisten vorkommende Unterfeld ist .keyword. In diesem wird der gesamte Inhalt des Feldes als einziger Term indexiert.
Term Indexierter Begriff. Ein Term ist eine Wert, welcher gesucht werden kann. Ein Feld kann einen oder mehrere Terms enthalten. Damit ein Treffer gefunden werden kann, muss immer ein ganzer Term gematched werden. Zum Beispiel, wenn der Term «Fussball» im Index ist und nach «Fusball» gesucht wird, ist dies kein Match. Man kann natürlich mit «Fus*ball» suchen und findet dann beide Varianten.
Event Ein Event ist eine Aktion die auf der Oberfläche von swissbib ausgeführt wurde. (Fast) jede Aktion löst einen http-Request aus, welcher dann vom Server in einer Logdatei vermerkt wird.
Time Range Die Time Range ist ein einfacher Filter, welcher eine zeitliche Eingrenzung der gefundenen Dokumente erlaubt. Die Grundeinstellung ist immer die letzten 15 Minuten. Das heisst es werden nur Events angezeigt, welche in den letzten 15 Minuten passiert sind. Um dies zu ändern muss oben rechts die Einstellung geändert werden. In Dashboards kann die Zeit mitgespeichert werden. Dort werden immer die letzten 30 Tage angezeigt.
Filter Der Filter ist eine Möglichkeit, gewisse Dokumente aus einer Suche auszuschliessen oder umgekehrt eine Suche nur auf gewisse Dokumente anzuwenden.
Such-Schlitz In allen Suchoberflächen «Discover», «Visualize» und «Dashboard» hat es oben einen Such-Schlitz, welcher es erlaubt, nach bestimmten Dokumenten zu suchen. In allen drei Oberflächen verhält sich dies genau gleich. Die Suche, welche implementiert ist, kann alles was man von einer Suche erwarten würde. Von einfacher Textsuche, zu Boolschen Operatoren (AND, OR, NOT) über Feldsuchen «feldname:suchbegriff» bis hin zu komplexen Regex Abfragen.

Index

In unserer Elasticsearch Instanz gibt es aktuell acht verschiedene Index. Die gesammelten Daten werden nach Plattform und Jahr unterteilt. Die aktuell vorhandenen Index sind:

  • swissbib-green-2017
  • swissbib-green-2018
  • swissbib-jus-2017
  • swissbib-jus-2018
  • swissbib-bb-2017
  • swissbib-bb-2018
  • sru-2017
  • sru-2018

Für das Jahr 2019 wird dann jeweils ein neuer Index erstellt und die Daten dort reingeschrieben.

Index Pattern / Sammelindex

Mit den Index Pattern werden folgende Index zusammengefasst:

  • swissbib-*
    • Beinhaltet alle sechs swissbib Indexe
  • sru-*
    • Beinhaltet die beiden sru-Indexe

Diesen Aufbau zu verstehen, ist wichtig um Suchabfragen und Filter richtig aufbauen zu können.

WICHTIG: Neue Visualisierungen sollen mit dem swissbib-* Index gemacht werden!

Felder / Unterfelder

Insgesamt hat der Sammelindex 189 Felder (die einzelnen Indexe haben etwas weniger, da nicht alle alle Felder haben). Diese Anzahl schliesst auch spezielle Felder ein, die Metadaten über die Dokumente enthalten und auch Unterfelder, welche vorhanden sind.

In diesem File kann die vollständige Liste der Felder eingesehen werden: Verzeichnis Felder

Ein paar wichtige Punkte:

  • Alle Text Felder haben ein Unterfeld «<>.keyword» (z.B. library_name.keyword). Dieses Feld hat denselben Wert wie das Hauptfeld «library_name», aber als einzelner Term indexiert.
  • Der Typ eines Feldes ist relevant dafür, welche Aggregationen darauf ausgeführt werden können. Nur von einer Nummer kann z.B. eine Summe gemacht werden.
  • Ein Feld kann eine spezielle Formatierung haben. Insbesondere kann ein Text-Feld als URL interpretiert werden. Dies wird an manchen Stellen genutzt, damit man direkt auf den Link drücken kann und dann auf die Webseite geleitet wird. Dies ist der Fall wie gewohnt auf allen blauen Texten die unterstrichen sind.
  • Die Unterfelder von filter_params beziehen sich i.d.R. auf Facettensuchen, während die Unterfelder von search_params sich auf die Parameter von Suchen und Erweiterten Suchen beziehen.


Logstash

Aktuell ist Logstash dafür da, um die rohen Log-Daten in das verwendete Datenmodel umzuwandeln.