nodes2grafana

Über nodes2grafana

nodes2grafana umfasst zwei Konverter (namens nodes2prom und graph2prom), welche die Statusdaten von FF-Routern aus 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 der Konverter in SML'97 programmiert ist.

• 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 der lokalen Community definiert (zB Meshes), die im Dashboard über ihren Namen (group="...") auswählbar sind. Welche Router zu einer besimmten Gruppe gehören, wird durch einen regulären Ausdruck (regex="...") angegeben.

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 der nodes.json erzeugte .prom Datei 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:

• Der Konverter nodes2prom und 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 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 Datei 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.)

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 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:-)

TODO

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