20171019 README.md (Mehr Infos zum Einrichten von node_exporter, prometheus, grafana)

README.md

@@ -1,10 +1,12 @@
 # Über nodes2grafana
 
-nodes2grafana ist ein Konverter für `nodes.json` -> prometheus Textformat. Mit dem erforderlichen Drumrum, incl. grafana Dashboards.
+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.
 
-Die Software befindet sich 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).
+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 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 (`nodes2prom`) angepasst werden, d.h. z.Z.: umprogrammiert.
+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
 
@@ -16,11 +18,12 @@ Nach erfolgreichem `make` (s.u.) findet sich der tarball in `dist/nodes2grafana.
 
 ## Benötigte Software
 
-Benötigt wird außer den üblichen verdächtigen Un*x-utilities nur [SML/NJ](http://www.smlnj.org/). Das smlnj package sollte vollständig sein, d.h. auch `ml-build` und `heap2exec` enthalten. Dies ist beim FreeBSD port lang/smlnj der Fall.
+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.
@@ -34,22 +37,30 @@ Anschließend:
     # make clean
     # rm Makefile
 
-Nach einem erfolgreichen `make` befinden sich im Verzeichnis `test/tmp` die Ergebnisse des Testlaufs (cd test && make).
+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. Das 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 sollte im Betrieb periodisch ausgeführt werden. S. `etc/crontab`.
+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
 
-Es genügt, den `node_exporter` nur mit dem textfile-Kollektor laufen zu lassen, um die ....prom Datei aus dem *EXPORT_DIR* für Prometheus verfügbar zu machen:
+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 <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](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:
@@ -60,22 +71,30 @@ 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
 
-In `grafana.conf` die von nodes2grafana nach *DASHBOARD_DIR* installierten Dashboards freischalten:
+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 <http://localhost:3000/> 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, ...)
+- 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:-)