kibconfig – Wartungstool für Kibana Dashboards

Als wir vor 2 Jahren zu Beginn unseres Projekts damit begannen, unser ELK Logging über Kibana Dashboards zu optimieren, standen wir vor einem Problem: Wie konnten wir unsere für die PP-Umgebung vorbereiteten Dashboards, Visualisierungen und gespeicherten Suchen auf die Produktionsumgebung überführen, ohne den gleichen Konfigurationsaufwand über die Oberfläche nochmal zu treiben? Außerdem wäre es schwierig, beide Umgebungen so synchron zu halten.

Eine Tool-Suche ergab leider nichts, aber es stellte sich heraus, dass alle Oberflächenelemente in einem ElasticSearch Index hinterlegt sind und als JSON exportier- und pflegbar sind. Damit entstand die Idee ein eigenes Tool dafür zu schreiben: kibconfig .

kibconfig erlaubt den Download und Upload der Kibana-Elemente (Dashboard, Visualization, Search, Config, Index-Pattern) in eine lokale Verzeichnisstruktur. Da die in ElasticSearch gespeicherten JSON-Dokumente wiederum als String verpackte JSON-Strukturen enthalten, werden diese dabei „ausgepackt“. Alle Attribute werden außerdem in einer definierten Reihenfolge und Pretty-Printed gespeichert, so dass ein einfaches Diffing und Versionierung – z. B. via Git- möglich ist. Seit der Version 0.2 ist auch ein einfaches „deep copy“ von Dashboards mitsamt Unterstrukturen möglich. Das verwenden wir z. B. zur Erstellung angepasster Dashboards für unterschiedliche Microservices.

Hier ein Beispiel eines unter ./dashboards/Example-Dashboard.json lokal gespeicherten Dashboards:

1{
2    "id": "Example-Dashboard",
3    "title": "Example Dashboard",
4    "description": "",
5    "hits": 0,
6    "timeRestore": false,
7    "version": 1,
8    "kibanaSavedObjectMeta": {
9        "searchSourceJSON": {
10            "filter": [
11                {
12                    "query": {
13                        "query_string": {
14                            "analyze_wildcard": true,
15                            "query": "*"
16                        }
17                    }
18                }
19            ]
20        }
21    },
22    "panelsJSON": [
23        {
24            "id": "Navigation",
25            "type": "visualization",
26            "col": 1,
27            "row": 1,
28            "size_x": 2,
29            "size_y": 5
30        },
31        {
32            "id": "Example-all-errors",
33            "type": "search",
34            "col": 3,
35            "row": 1,
36            "size_x": 10,
37            "size_y": 4,
38            "columns": [
39                "hostname",
40                "category",
41                "message"
42            ],
43            "sort": [
44                "timestamp",
45                "desc"
46            ]
47        },
48        {
49            "id": "Example-Log-count-by-level",
50            "type": "visualization",
51            "col": 3,
52            "row": 5,
53            "size_x": 10,
54            "size_y": 4
55        }
56    ]
57}

Über Profile lassen sich in einer Konfigurationsdatei verschiedene Zielumgebungen ansprechen. Damit ist ein Staging der Konfiguration sehr einfach möglich.

Anwendungsmöglichkeiten

Die Pflege der Dashboards gestaltet sich damit wesentlich einfacher:

• Kleinere aber oft übergreifende Anpassungen, wie z. B. bei Schema-Änderungen, lassen sich jetzt einfach über Suchen-/Ersetzen in der IDE lösen.
• Je nach Änderung kann der Entwickler entscheiden, ob die Änderungen zunächst im Repository oder in Kibana vorgenommen werden. Letzteres is insbesondere beim Layouting ratsam.
• Änderungen können in Branches vorbereitet, und per Merge Request reviewed werden.
• Die Versionierung erlaubt die einfache Durchführung von Rollbacks.
• Falls zwischenzeitig doch mal z. B. durch Dritte  manuelle Änderungen an Kibana Boards vorgenommen wurden, lässt sich das einfach über einen erneuten Download und Diff zum Repository-Stand feststellen und beheben.

Anwendungsfall: Migration auf eine neue ELK/Kibana Version

Vor kurzem Stand ein Update unseres ELK Stacks 1.x/Kibana 4 auf ELK 5.x/Kibana 5 an, einhergehend mit einem neuen Index- und Schemakonzept. Die grundlegenden Datenstrukturen haben sich bei Kibana 5 dankenswerterweise kaum geändert. Die aus Kibana 4 exportierten Dateien waren daher problemlos in Kibana 5 importierbar. Es waren daher nur noch folgende Schritte notwendig:

• Die Schemaänderung bedeutete, dass wir über alle Dateien die Feldnamen um einen Prefix erweitern mussten, was über mehrfaches globales Suchen und Ersetzen in IntelliJ schnell erledigt war.
• Gleiches galt für den Indexnamen, der überall zu ersetzen war.
• Die bisherigen Felder wurden teilweise für Aggregationen benutzt. Das ging für numerische und Datumsfelder weiterhin ohne Anpassung, für Textfelder musste allerdings der Feldname um den Postfix .keyword erweitert werden.
• Das Dashboard-Layout hatte sich leicht geändert. Die Layoutanpassungen haben wir abschließend direkt in Kibana vorgenommen.

Über diesen Weg haben wir alle Dashboards innerhalb eines Tages migrieren können.

kibconfig ist als kostenloses Tool unter der GPL v3 bei GitHub verfügbar . Euer Feedback und Pull Requests werden dankend angenommen.