nodes2grafana

Über nodes2grafana

nodes2grafana umfasst einen Konverter (namens nodes2prom), der die Statusdaten von FF-Routern aus der nodes.json in das Prometheus Textformat umwandelt, 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 und FF-DO-status-group. 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 dortige nodes.json die gleiche Struktur hat wie in Dortmund. Ansonsten müsste der Konverter (src/nodes2prom.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 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 von executables genutzt. Ansonsten wird ein script installiert, dass einen heap mit Hilfe der SML/NJ runtime ausführt.
• Für auf Debian basierende Distributionen benötigt man außer dem smlnj package auch das ml-lpt package.

Konfiguration

Zwecks Konfigurationsanpassung (Pfade, Metriknamen, Community) die Datei conf/substitutions.conf.default nach /etc/nodes2grafana.conf kopieren und die zu ändernden Werte anpassen.

Zeilen, die gegenüber der substitutions.conf.default nicht geändert wurden, können auch weggelassen werden.

Will man nicht gleich im /etc herumschreiben sondern erstmal ausprobieren, kann man conf/substitutions.conf.local verwenden.

Anschließend:

Bauen

make -C conf && make
# make install
# 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.

Betreiben

nodes2prom

Durch make install werden der Konverter nodes2prom und ein script nodes2prometheus.sh nach BIN_DIR installiert. Dieses script fetcht die nodes.json von der angegebenen NODES_URL und konvertiert sie mit nodes2prom zu einer .prom-Datei nach EXPORT_DIR. Das script nodes2prometheus.sh sollte im Betrieb periodisch ausgeführt werden. S. etc/crontab.

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

json-pp nodes.json nodes.json.pp

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 ü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: http://localhost:9090/graph?g0.range_input=1h&g0.expr=ffdo_nodes_detail_clients&g0.tab=1. (Wenn man die substitutions.conf 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.

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)
• graph.json -> grafana
• 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:-)