-5- 20171019 README.md (nodes2grafana ist dank substitutions.conf nicht Dortmund-spezifisch; Hinweise zum Betrieb des daemon-Zoos)

README.md

@@ -1,43 +1,82 @@
-# nodes2grafana
-
-## Über diese Software
+# Über nodes2grafana
 
 nodes2grafana ist ein Konverter für `nodes.json` -> prometheus Textformat. Mit dem erforderlichen Drumrum, incl. grafana Dashboards.
 
-### Herunterladen
+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).
 
-Den Inhalt dieses repository's kann man sich hier als tarball herunterladen: <https://git.ffdo.de/altlast/nodes2grafana/archive/master.tar.gz>.
+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.
 
-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.
+# Installation
+
+## Herunterladen
 
-## Installation
+Den aktuellen Stand dieses repository's kann man sich hier als tarball herunterladen: <https://git.ffdo.de/altlast/nodes2grafana/archive/master.tar.gz>. Oder das repository mit `git` klonen: <https://git.ffdo.de/altlast/nodes2grafana.git>.
 
-### Benötigte Software
+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/). 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
+## Konfiguration
 
-Zwecks Konfigurationsanpassung (Pfade, Metriknamen) die Datei `conf/substitutions.conf.default` nach `/etc/nodes2grafana.conf` kopieren und die zu ändernden Werte anpassen.
+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
+## Bauen
 
-    cd conf && make && cd .. && make
+    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).
 
+## 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`.
+
+### 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:
+
+    node_exporter -web.listen-address=localhost:9100 -collector.textfile.directory=/var/tmp/node_exporter -collectors.enabled=textfile
+
+### prometheus
+
+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
+
+### grafana
+
+In `grafana.conf` die von nodes2grafana nach *DASHBOARD_DIR* installierten Dashboards freischalten:
+
+    [dashboards.json]
+    ;enabled = false
+    enabled = true
+    path = /var/db/grafana/dashboards
+
+Startparameter zB:
+
+    grafana-server -config=/usr/local/etc/grafana.conf -homepath=/usr/local/share/grafana/
+
 # TODO
 
 - Auch für GNU/Linux gängig machen (gmake, wget, sed etc., pax, install, ...)
-- status-group dashboard
 - `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:-)