# Über nodes2grafana nodes2grafana umfasst einen Konverter (namens `nodes2prom`), der die Statusdaten von FF-Routern aus der `nodes.json` in das [Prometheus Textformat](http://prometheus.io/docs/instrumenting/exposition_formats/) 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](http://vm23.free.de:3000/dashboard/file/FF-DO-status.json) und [FF-DO-status-group](http://vm23.free.de:3000/dashboard/file/FF-DO-status-group.json). Sowie die Wiki-Seite zum FF-DO-[Status](http://url.free.de/ffdo/Technik/Netzinfrastruktur/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: . Oder das repository mit `git` klonen: . 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](http://www.smlnj.org/), 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. - Für auf Debian basierende Distributionen benötigt man 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 ## nodes2prom Das script `nodes2prometheus.sh` besorgt die aktuelle `nodes.json` von der angegebenen *NODES_URL* und konvertiert sie mit `nodes2prom` 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](https://github.com/prometheus/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 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](https://prometheus.io/) 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": . Ggf. auf Fehlermeldungen achten (prometheus.log). Und ob er sinnvolle Daten bekommt, zB: . (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](https://grafana.org/) 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 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](http://www.smlnj.org/sml.html) unterwegs ist ... :) - Doku:-)