# Ü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 den ü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. auch `ml-build` und `heap2exec` enthalten. Dies ist beim FreeBSD port lang/smlnj der Fall. ## 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 `fetch`t 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](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` ü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: . (Wenn man die substitutions.conf 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 sollte Grafana über erreichbar sein, und man kann darüber den lokalen Prometheus als (default-)Datenquelle konfigurieren. Anschließend sollten die von nodes2grafana installierten Dashboards funktionieren, d.h. "bunte Bilder" produzieren:-) # TODO - Auch für GNU/Linux gängig machen (gmake, wget, sed etc., pax, install, ...). Das sollte einfach sein, da die Makefiles zwecks leichter Portierbarkeit sehr minimalistisch formuliert sind. - `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:-)