# Ü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](http://prometheus.io/docs/instrumenting/exposition_formats/) 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](http://vm23.free.de:3000/dashboard/file/FF-DO-status.json), [FF-DO-status-group](http://vm23.free.de:3000/dashboard/file/FF-DO-status-group.json) und [FF-DO-status-mesh](http://vm23.free.de:3000/dashboard/file/FF-DO-status-mesh.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.](#konfiguration)) 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: . Oder das repository mit `git` klonen: . Nach erfolgreichem `make` ([s.u.](#bauen)) 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 die Konverter in [Standard ML](https://en.wikipedia.org/wiki/Standard_ML) (Sprachdefinition: [SML'97](http://sml-family.org/sml97-defn.pdf)) 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](http://url.free.de/ffdo/Technik/Routing/Fussgaengerzonenproblem), 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](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. In der Prometheus-Console (:9090/graph) gibt es hilfsweise auch ein pop-up Menu für die zZ bekannten Metriknamen.) ## grafana Mit [Grafana](http://docs.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. Damit auch Tortengrafiken in den Dashboards funktionieren, benötigt man das [Pie-Chart-Panel Plugin](https://grafana.com/plugins/grafana-piechart-panel), s. [Installationsanleitung](https://grafana.com/plugins/grafana-piechart-panel/installation). Startparameter für Grafana 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:-) # 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](http://www.freifunk-dortmund.de/). 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](http://www.smlnj.org/sml.html) unterwegs ist ... :) - Doku!-)