Motivation

Es ist einfach und praktisch, in Kibana interaktiv Dashboards zu gestalten. Oft möchte man aber verschiedene Varianten eines Dashboards haben, beispielsweise für unterschiedliche Umgebungen oder Kunden. Oder man möchte exakt dieselben Positionen für Dashboard-Elemente oder dieselben Farben verwenden. Dann wird es mühsam, alles interaktiv zu gestalten. Einfacher und effizienter ist es in solchen Fällen, wenn Dashboards mit Hilfe von Variablen automatisch generiert werden können.

Idee

Templates und ein einfacher Template-Prozessor (Template-Engine) können verwenden werden, um flexibel Kibana Dashboards zu generieren.

Diese Idee lässt sich für viele andere Automatisierungslösungen analog brauchen und ist keine spezielle Idee für Kibana Dashboards. Ursprünglich wurden Template-Prozessoren vor allem verwendet, um HTML-Seiten zu generieren.

Folgende Komponenten sind nötig:

Inputdatei(en) mit Variablen
Template als Textdatei
Template-Prozessor

Der Template-Prozessor generiert aus dem Template zusammen mit den Inputdatei(en) Outputdatei(en) wie beispielsweise Konfigurationsdatei oder Dateien in einem der folgenden Formate: html, xml, json, ndjson oder was immer im gegebenen Kontext gebraucht wird.

Der Template-Prozessor muss mindestens einfache mathematische Operationen (Addition, Multiplikation, Modulo), Schleifen und Bedingungen ausführen können und nicht nur Texte ersetzen oder generieren. Siehe auch http://www.simple-is-better.org/template/index.html.

Gewählte Werkzeuge

Json-Dateien werden für die Inputdatei mit Variablen verwendet, aber es sind auch yaml-Dateien oder weitere Formate möglich.

Der Python-Template-Prozessor Jinja2 wird als Template-Prozessor verwendet. Python ist weit verbreitet und Jinja2 wird ebenfalls oft verwendet, beispielsweise in Ansible.

Jinja2 kann in Python-Skripts verwendet werden. Einfacher ist es für das Generieren von Dashboards aber, ein fertiges Kommandozeilenwerkzeug zu verwenden. Für komplexere Anwendungen kann dieses auch aus einem Shellskript aufgerufen werden. Hier wird jinjanator gebraucht, das aktiv weiterentwickelt wird. Eine Alternative wäre yasha, das gut funktioniert, aber etwas älter ist.

Es gibt noch viele weitere Alternativen für Template-Prozessoren, z.B. das Perl Template Toolkit. Dieses ist viel mächtiger als Python und jinja2, wird aber nicht mehr wirklich weiterentwickelt.

Für eine Liste von Template-Prozessoren siehe z.B.: https://en.wikipedia.org/wiki/Comparison_of_web_template_engines

Wenn Python installiert ist, werden Jinja2 und jinjanator mit pip installiert:

pip install Jinja2
pip install jinjanator

VisualStudioCode (VSCode) wird als Editor für die Inputdateien und Templates gebraucht. VSCode kann unter Windows, Linux und gut auch in Windows WSL2 gebraucht werden und es gibt für VSCode gute Unterstützung für Python und json-Dateien mit Extensions im VSCode-Marketplace.

Für das Erstellen der Templates empfehle ich, VSCode mit der Extension vscode-json zusammen mit der Python Extension von Microsoft zu verwenden.

Umsetzung für Kibana Dashboards

Voraussetzungen

Kibana Dashboards haben wie andere Kibana Saved-Objects eine Repräsentation als ndjson-Datei. Solche ndjson-Dateien können aus Kibana exportiert und in Kibana importiert werden.

Ndjson-Dateien sind Textdateien und lassen sich generieren, um flexibel Dashboards zu erstellen.

Ndjson-Dateien mit Dashboarddefinitionen

Ndjson steht für «Newline delimited json». Es ist ein Standard für Dateien, die pro Zeile ein json-Dokument enthalten. Das ist sehr praktisch, um in Kibana mehrere Objekte in eine einzelne Datei zu exportieren oder aus einer Datei zu importieren. Die Dateien haben aber sehr lange Zeilen und sie sind deshalb nicht gut geeignet, um interaktiv Änderungen an ihnen vorzunehmen.

Das ndjson-Format für Dashboards ist nicht dokumentiert ausser im Code von Kibana. Manchmal braucht es etwas Fantasie um das Format zu verstehen. Tests und einfache Beispiele können dabei helfen. Das Nachführen für neue Kibana-Versionen kann deshalb aufwändig sein und man hat keinen guten Überblick darüber, was wirklich alles möglich wäre beim Generieren von Dashboards aus Programmen heraus.

Ein paar Hinweise zum ndjson-Format für Dashboards können folgende Dateien im Code von Kibana liefern:

Dashboard als Vorlage

In Kibana wird zuerst interaktiv ein Dashboard erstellt, das dann als Grundlage für ein Template dient. In der Vorlage sollten Panels, die im generierten Dashboard mehrmals platziert werden sollen, bereits mehrfach vorkommen. Möglichst alle Elemente und Einstellungen, die gebraucht werden, sollten schon in der Vorlage vorkommen, damit deren Repräsentation im ndjson-File des Dashboards schon vorhanden ist.

Dashboard exportieren

In Elastic können unter dem Menüpunkt «Management → Stack Management → Saved Objects» Dashboards (und weitere gespeicherte Objekte) exportiert und als ndjson-Dateien gespeichert werden.

Es empfiehlt sich, sowohl das Dashboard, das als Vorlage dient, als auch die ndjson-Datei mit dem exportierten Dashboard zu sichern. Nach Kibana Updates kann dann das aktualisierte Dashboard neu exportiert und mit der alten, exportierten Version verglichen werden. Das hilft, um dann auch Templates für das Generieren von Dashboards an neue Kibana-Versionen anzupassen.

Inputdatei mit Variablen

Es muss eine json-Inputdatei mit allen Variablen, die im generierten Dashboard vorkommen sollen, geschrieben werden. Es empfiehlt sich auch, einen Titel (Namen) für das Dashboard in der Inputdatei zu definieren, damit man im Kibana-GUI die Dashboards unterscheiden kann. Das genaue Format der Inputdatei ist nicht so wichtig, es muss nur auf einfache Weise auf die Werte zugegriffen werden können.

Durch Anpassungen an den Inputdateien oder die Verwendung verschiedener Inputdateien können dann unterschiedliche Dashboards erzeugt werden.

Umformen der ndjson-Datei mit dem Dashboard

Ndjson-Dateien sind für interaktive Änderungen in VSCode nicht geeignet, da sie lange Zeilen aufweisen und nicht gut lesbar sind. Zudem sind es keine gültigen json-Dateien und viele json-Editoren und Erweiterungen haben Mühe, mit ihnen umzugehen.

Eine weitere Schwierigkeit ist es, dass die Angaben zu den Dashboard-Panels, die angepasst werden sollen, in Arrayelementen stehen, die eigentlich wieder json-Teile enthalten. Da sich aber in json so etwas nicht verschachtelt definieren lässt, braucht es dort vor Anführungs- und Schlusszeichen und vor weiteren Spezialzeichen wie den Backslashes als Escape-Zeichen einen vorangestellten Backslash. Hier muss man aufpassen, dass bei Umformatierungen diese Backslashes erhalten bleiben, sonst kann die am Ende generierte ndjson-Datei nicht mehr in Kibana importiert werden.

Am einfachsten ist es, wenn man die Dateien vor dem Editieren in VSCode formatiert und danach die Formatierung wieder rückgängig macht. Dazu dienen die folgenden Schritte:

Kopieren der ndjson-Datei mit dem Dashboard in eine Datei mit der Extension .j2. So bleibt die ursprüngliche Datei erhalten. Das Ändern der Dateiextension ist nicht wirklich nötig, kennzeichnet aber die Datei als Datei mit jinja2-Elementen.
Kopieren der Zeile mit der benötigten Dashboard-Definition und speichern dieser Zeile in einer eigenen, temporären Datei mit der Extension .json.
Öffnen der json-Datei mit der Dashboarddefinition in VSCode.
Umwandeln in eine besser lesbare, formatierte json-Datei mit <ctrl><alt><b> (vscode-json: Beautify).
Bei Bedarf im Teil mit der Dashboard-Panel-Definition Zeilenumbrüche und weitere Zeichen einfügen, damit die Datei besser editiert werden kann. Das kann mit einem Replace der Kommata im Editor gemacht werden, bei dem ein Zeilenumbruch und eine Zeichenfolge, die sonst in der Datei nicht vorkommt, eingefügt wird.
Editieren der Datei und jinja2-Elemente einfügen.
Die allenfalls in Schritt 5 eingefügten Zeilenumbrüche und Zeichenfolgen wieder löschen.
Sicherheitshalber Ids löschen, damit beim späteren Import neue Ids generiert werden und keine Konflikte entstehen. Insbesondere darf es nicht mehrere Dashboards mit derselben Id in einer Datei geben, sonst gibt es später einen Fehler beim Import.
Formatierung der Datei wieder zurücksetzen mit <ctrl><alt><u> (vscode-json: Uglify).
Die Zeile mit dem Dashboard-Template kopieren und in der in Schritt 1 erstellten j2-Datei die Dashboard-Definition damit ersetzen.

Template mit jinja2

Im Schritt 6 von oben wird interaktiv ein Template mit jinja2 Variablen und Ausdrücken erstellt. Die Variablen und Ausdrücke verwenden die Definitionen der Werte aus der Inputdatei. Die Dokumentation zu Jinja2 findet man hier: https://jinja.palletsprojects.com/en/stable/templates

Zur Dokumentation des Templates können jinja2-Kommentare der Form {# Kommentartext #} direkt in die Templatedatei eingefügt werden.

Template-Prozessor

Mit dem Template-Prozessor jinja2 kann nun aus der Inputdatei mit den Variablen und der jinja2-Templatedatei eine ndjson-Datei mit dem generierten Dashboard erzeugt werden. Dafür kann jinjanate auf der Kommandozeile gebraucht werden.

jinjanate template_datei.j2 inputdatei_vars.json -o generiertes_dashboard.ndjson

Dashboard importieren

In Elastic können unter dem Menüpunkt «Management → Stack Management → Saved Objects» Dashboards (und weitere gespeicherte Objekte) interaktiv aus ndjson-Dateien importiert werden. Hier kann nun das generierte Dashboard in Kibana importiert werden.

Am besten wählt man dabei die Option «Create new objects with random Ids» aus, damit Konflikte mit Ids möglichst vermieden werden.

Beispiele gewünscht?

Gespannt auf die ersten Anwendungsbeispiele? Diese finden Sie in einer Woche in unserem nächsten Teil dieses Blogbeitrags.

Natürlich können Sie jederzeit auf Swissmakers zukommen für Unterstützung bei der Erstellung professioneller Kibana-Dashboards.

Matthias Dillier

Mathematiker, Informatiker und Saxophonist mit langjähriger Erfahrung in diversen Bereichen der Informatik. Aktuell befasst er sich besonders mit Monitoring, Problemanalysen, Logauswertungen, Grafiken und der Automatisierung von Betriebsprozessen.