# Ü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 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 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 für die lokale Community die Datei `conf/substitutions.conf.franchise` editieren. Wenn Bedarf an weiteren lokalen Anpassungen besteht, dann nach dem untigen `make` die `conf/substitutions.conf` nach `/etc/nodes2grafana.conf` kopieren und editieren. Ein Bezeichner (erstes Feld) wird durch Tabulator-Zeichen vom Substitutions-Wert getrennt. Zeilen, die gegenüber der substitutions.conf nicht geändert wurden, können (und sollten) weggelassen werden. Will man nicht gleich im /etc herumschreiben sondern erstmal ausprobieren, kann man statt `/etc/nodes2grafana.conf` einfach `conf/substitutions.conf.local` verwenden. Für die Anpassung der status-group Dashboards an die lokale Community auch die Datei `dashboard/groups.prom.in` editieren. (Bei späteren Änderungen eines dortigen "regex"-labels immer den count hochzählen!) 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 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:-)