nodes2grafana

Über nodes2grafana

nodes2grafana umfasst zwei Konverter (namens nodes2prom und graph2prom), welche die Statusdaten von FF-Routern aus der Datei nodes.json bzw. graph.json in das Prometheus Textformat umwandeln, sowie dazu passende Grafana-Dashboards zur Visualisierung.

Damit aus den konvertierten Statusdaten bunte Bildchen werden, die alle FreifunkerInnen begeistern, braucht es zusätzlich die daemons node_exporter, prometheus und grafana-server. Hinweise dazu finden sich weiter unten.

nodes2grafana läuft zZ in Dortmund im Probebetrieb, s. die Dashboards FF-DO-status, FF-DO-status-group und FF-DO-status-mesh. Sowie die Wiki-Seite zum FF-DO-Status.

nodes2grafana ist aber nicht spezifisch für die Dorfmunder FF-Community, sondern kann durch Editieren einer Konfigurationsdatei (s.u.) von anderen Communities umge*brand*et werden:-) Zumindest, wenn die dortigen nodes.json und graph.json die gleiche Struktur haben wie in Dortmund. Ansonsten müssten die Konverter (src/nodes2prom.sml und src/graph2prom.sml) angepasst werden, d.h. z.Z.: umprogrammiert.

Installation

Herunterladen

Den aktuellen Stand dieses repository's kann man sich hier als tarball herunterladen: https://git.ffdo.de/altlast/nodes2grafana/archive/master.tar.gz. Oder das repository mit git klonen: https://git.ffdo.de/altlast/nodes2grafana.git.

Nach erfolgreichem make (s.u.) findet sich der tarball in dist/nodes2grafana.txz. Hat man lokale Modifikationen an der Software vorgenommen, so sind sie im tarball enthalten, sofern man dist/Makefile.in ggf. angepasst hat.

Benötigte Software

Benötigt wird außer FreeBSD oder GNU/Linux sowie den dort üblichen verdächtigen Un*x-utilities nur SML/NJ, da die Konverter in Standard ML (Sprachdefinition: SML'97) programmiert sind.

• Das smlnj package sollte vollständig sein, d.h. muss auch ml-build enthalten.
• Wenn heap2exec vorhanden ist (wie beim FreeBSD port lang/smlnj), dann wird es zur Erstellung der executables genutzt. Ansonsten wird ein Hilfsscript installiert, das einen heap mittels der SML/NJ runtime ausführt.
• Auf Debian basierende Distributionen benötigen außer dem smlnj package auch das ml-lpt package.

Konfiguration

conf/substitutions.conf.local

make -C conf

Dabei wird zunächst die Datei conf/substitutions.conf.default aus den Dateien conf/substitutions.conf.franchise (Community-spezifische Einstellungen) und conf/substitutions.conf.FreeBSD bzw. ....Linux (OS-spezifische Einstellungen) zusammenkopiert.

Wenn Bedarf an lokalen Anpassungen besteht, dann

cp conf/substitutions.conf.default conf/substitutions.conf.local
vi conf/substitutions.conf.local

Beim Editieren beachten:

• Ein Bezeichner (erstes Feld) wird durch Tabulator-Zeichen vom Substitutions-Wert (Rest der Zeile) getrennt.
• Zeilen, die gegenüber der substitutions.conf.default nicht geändert wurden, sollten weggelassen (gelöscht oder #auskommentiert) werden.

Nach Erstellung der substitutions.conf.local nochmals ...

make -C conf

... damit die Anpassungen wirksam werden. Ist man schließlich mit seiner substitutions.conf.local zufrieden, kann man sie durch ...

mv conf/substitutions.conf.local /etc/nodes2grafana.conf

... nachhaltig wirksam machen.

dashboard/groups.prom.in

Für die Nutzung der status-group Dashboards empfiehlt sich

vi dashboard/groups.prom.in

In dieser Datei werden Routergruppen (zB Fußgängerzone, Dorf, Mesh) der lokalen Community definiert, die im status-group-Dashboard über einen frei gewählten Namen (group="...") auswählbar sind. Welche Router zu einer bestimmten Gruppe gehören, wird durch einen regulären Ausdruck (regex="...") angegeben, der natürlich genau die gewünschten Routernamen matchen sollte.

Bitte beachten: Bei späteren Änderungen eines "regex"-labels in der groups.prom.in immer den count um 1 hochsetzen! (Das ist die Zahl am Ende einer Zeile.)

Bauen

make -C conf && make
# make clean
# rm Makefile

Nach einem erfolgreichen make befinden sich im Verzeichnis test/tmp die Ergebnisse des Testlaufs (cd test && make). Die dort aus nodes.json bzw. graph.json erzeugten *.prom Dateien sollte man in Augenschein nehmen, ehe man fortfährt.

Installieren

daemons

FreeBSD: pkg install node_exporter prometheus grafana4

Debian & Co.: apt install prometheus prometheus-node-exporter grafana

nodes2grafana

make install

Dadurch werden installiert:

• Die Konverter nodes2prom und graph2prom, sowie ein script nodes2prometheus.sh nach BIN_DIR.
• Die Dashboards nach DASHBOARD_DIR.
• Die Konfiguration der Routergruppen (*-groups.prom) für das status-group Dashboard nach EXPORT_DIR.
• Ein Eintrag in der /etc/crontab (wenn vorhanden) zum regelmäßigen Aufruf von nodes2prometheus.sh

Außerdem wird die utility json-pp (JSON pretty printer) nach BIN_DIR installiert. Diese kann man benutzen, um unformatierte JSON-Dateien humankompatibel lesbar zu machen, zB so: json-pp nodes.json nodes.json.pp.

Betrieb

Wie die Daemons genau gestartet werden, hängt vom verwendeten Betriebssystem ab. Bei FreeBSD s. /etc/rc.conf, bei Debian et al. s. systemd.

nodes2prom

Das script nodes2prometheus.sh besorgt die aktuellen nodes.json und graph.json von der angegebenen NODES_URL bzw. GRAPH_URL und konvertiert sie mit nodes2prom bzw. graph2prom zu je einer .prom-Datei nach EXPORT_DIR. nodes2prometheus.sh sollte also im Betrieb periodisch ausgeführt werden. S. etc/crontab und /etc/crontab bzw. die entsprechende cron-Mechanik des verwendeten Betriebssystems.

node_exporter

Um die .prom Dateien aus dem EXPORT_DIR für Prometheus verfügbar zu machen, genügt es, den lokalen node_exporter nur mit dem textfile-Kollektor laufen zu lassen. ZB so:

node_exporter -web.listen-address=localhost:9100 -collector.textfile.directory=/var/tmp/node_exporter -collectors.enabled=textfile

Die konvertierten Daten sollten nun unter der Adresse http://localhost:9100/metrics abrufbar sein. Per Webbrowser oder fetch bzw. wget überprüfen. Außerdem auf Fehlermeldungen des node_exporter's achten, ehe man fortfährt.

prometheus

Prometheus ist der Datenbunker für die Zeitreihen (von Messwerten / Metriken). Er fragt periodisch Datenquellen (wie den node_exporter) nach aktuellen Metrikinformationen ab, speichert diese effizient, und ermöglicht das Abfragen der über die Zeit gebunkerten Daten.

In prometheus.yaml das "Scrapen" des lokalen node_exporter konfigurieren:

scrape_configs:
  static_configs:
    - targets: ['localhost:9100']

Startparameter zB:

prometheus -config.file=/usr/local/etc/prometheus.yml -storage.local.path=/data/prometheus -storage.local.target-heap-size=536870912 -storage.local.chunk-encoding-version=2 -storage.local.retention 336h0m0s

Überprüfen, ob Prometheus den node_exporter "scraped": http://localhost:9090/targets. Ggf. auf Fehlermeldungen achten (prometheus.log). Und ob er sinnvolle Daten bekommt, zB: http://localhost:9090/graph?g0.range_input=1h&g0.expr=ffdo_nodes_detail_clients&g0.tab=1. (Wenn man den Wert für PROM_STATS_PREFIX in der Konfiguration nicht verändert hat, ansonsten in der URL den modifizierten Metriknamen verwenden. In der Prometheus-Console (:9090/graph) gibt es hilfsweise auch ein pop-up Menu für die zZ bekannten Metriknamen.)

grafana

Mit Grafana kann man Daten u.a. aus Prometheus abfragen und visualisieren.

Für unsere Zwecke benötigen wir in der grafana.conf folgenden Konfigurationsschnipsel:

[dashboards.json]
;enabled = false
enabled = true
path = /var/db/grafana/dashboards

Dadurch werden die von nodes2grafana nach DASHBOARD_DIR installierten Dashboards freigeschaltet. Dabei muss der path in der grafana.conf natürlich mit dem Wert von DASHBOARD_DIR in unserer conf/substitutions.conf übereinstimmen.

Damit auch Tortengrafiken in den Dashboards funktionieren, benötigt man das Pie-Chart-Panel Plugin, s. Installationsanleitung.

Startparameter für Grafana zB:

grafana-server -config=/usr/local/etc/grafana.conf -homepath=/usr/local/share/grafana/

Nun ist Grafana über http://localhost:3000/ erreichbar, und man kann darüber den lokalen Prometheus als (default-)Datenquelle konfigurieren. Dadurch sollten die von nodes2grafana installierten Dashboards funktionieren, d.h. "bunte Bilder" produzieren:-)

Nutzung

Im status-Dashboard (dashboard/status.json.in) gibt es eine aufklappbare Anleitung für dieses Dashboard ("> Das was keiner liest"). Diese sollte auch NutzerInnen, die noch nicht mit Grafana-Dashboards gearbeitet haben, den Einstieg erleichtern.

Die Dashboards gibt es in doppelter Ausfertigung: dashboard/status*.json.in und dashboard/status*-render.json.in. Diese unterscheiden sich nur dadurch, dass in der "-render"-Version die Legenden zu den Grafiken nicht rechts neben, sondern unter den Grafiken angeordnet sind, und dass alle Spalten (min, max, avg, current) sichtbar sind. Dies dient vor allem dazu, dass Grafana (mittels phantomjs!) die Grafiken zu statischen Bildern fester Größe (PNG) umrechnet ("rendert"), die dann zB in Webseiten der Community eingebunden werden können (und dort auch ohne JavaScript funktionieren:). Ein Beispiel findet sich auf der Startseite des FF-Dortmund.

Natürlich sind die zZ "mitgelieferten" Dashboards längst nicht alles, was man aus der Datenbasis (nodes.json und graph.json) herausholen und darstellen kann. Wer weitere Dashboards (zB zu Firmware- und Hardwareverteilungen, reboot-Häufigkeiten etc. pp.) beitragen möchte, ist herzlich dazu eingeladen. Verbesserungen (insb. Vereinfachungen;) der "mitgelieferten" Dashboards werden auch gerne gesehen.

TODO

• Auch für GNU/Linux gängig machen: heap2exec. (Problem: 32bit runtime und ld auf 64bit Maschine)
• Bei Bedarf (zB für nodes.json Version 2): Aus einer textuellen Spezifikation der Struktur der nodes.json den passenden Konverter generieren. (Sportlich, aber wenn man eh' schon mit einer Meta-Sprache wie SML unterwegs ist ... :)
• Doku!-)