20171026 README.md (mehr zu Konfiguration und Installation)

Makefile.in

@@ -60,10 +60,12 @@ install: install-bin install-crontab install-dashboard
 install-bin: src/nodes2prom src/json-pp etc/nodes2prometheus.sh %%HEAP_FILES%%
 	%%INSTALL_BIN_CMD%% $> %%BIN_DIR%%
 
-install-crontab: etc/crontab
-	grep nodes2prometheus.sh %%ETC_DIR%%/crontab > /tmp/crontab.old || \
-	cat $> >> %%ETC_DIR%%/crontab
-	-diff /tmp/crontab.old $>
+install-crontab:
+	[ ! -r %%ETC_DIR%%/crontab ] || { \
+	cp -p %%ETC_DIR%%/crontab /tmp/crontab.old && \
+	grep nodes2prometheus.sh %%ETC_DIR%%/crontab > /tmp/crontab.n2g || \
+	cat etc/crontab >> %%ETC_DIR%%/crontab ; \
+	diff /tmp/crontab.old %%ETC_DIR%%/crontab || true ; }
 
 install-dashboard:
 	cd dashboard && ${MAKE} install

README.md

@@ -18,52 +18,86 @@ Nach erfolgreichem `make` (s.u.) findet sich der tarball in `dist/nodes2grafana.
 
 ## 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.
+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 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.
+- 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.
 - 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.
+### conf/substitutions.conf.local
 
-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.
+    make -C conf
 
-Will man nicht gleich im /etc herumschreiben sondern erstmal ausprobieren, kann man statt `/etc/nodes2grafana.conf` einfach `conf/substitutions.conf.local` verwenden.
+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.
 
-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!)
+Wenn Bedarf an lokalen Anpassungen besteht, dann
 
-Anschließend:
+    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 der lokalen Community definiert (zB Meshes), die im Dashboard über ihren Namen (group="...") auswählbar sind. Welche Router zu einer besimmten Gruppe gehören, wird durch einen regulären Ausdruck (regex="...") angegeben.
+
+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 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
+## Installieren
+
+    make install
+
+Dadurch werden installiert:
+
+- Der Konverter `nodes2prom` und 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`
 
-### nodes2prom
+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`.
 
-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`.
+# Betrieb
 
-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:
+## nodes2prom
 
-	json-pp nodes.json nodes.json.pp
+Das script `nodes2prometheus.sh` besorgt die aktuelle `nodes.json` von der angegebenen *NODES_URL* und konvertiert sie mit `nodes2prom` zu 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
+## 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 <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.
+Die konvertierten Daten sollten nun unter der Adresse <http://localhost:9100/metrics> 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
 
 [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. 
 
@@ -77,9 +111,9 @@ 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.)
+Überprüfen, ob Prometheus den node_exporter "scraped": <http://localhost:9090/targets>. Ggf. auf Fehlermeldungen achten (prometheus.log). Und ob er sinnvolle Daten bekommt, zB: <http://localhost:9090/graph?g0.range_input=1h&g0.expr=ffdo_nodes_detail_clients&g0.tab=1>. (Wenn man den Wert für *PROM_STATS_PREFIX* in der Konfiguration nicht verändert hat, ansonsten in der URL den modifizierten Metriknamen verwenden.)
 
-### grafana
+## grafana
 
 Mit [Grafana](https://grafana.org/) kann man Daten u.a. aus Prometheus abfragen und visualisieren.
 

conf/Makefile

@@ -8,18 +8,18 @@ substitutions.sed: substitutions.conf
 		-e 's@^([[:alnum:]_]+)	*(.*)@s!%%\1%%!\2!g@p' \
 		substitutions.conf > $@
 
-substitutions.conf: substitutions.conf.default substitutions.conf.local substitutions.conf.franchise
+substitutions.conf: substitutions.conf.default substitutions.conf.local
 	cp -p substitutions.conf.local $@
-	awk '{ print $$1 }' substitutions.conf.local | fgrep -v -h -f - substitutions.conf.default substitutions.conf.franchise >> $@
+	awk '{ print $$1 }' substitutions.conf.local | fgrep -v -h -f - substitutions.conf.default >> $@
+
+substitutions.conf.default: substitutions.conf.franchise substitutions.conf.FreeBSD substitutions.conf.Linux
+	cat substitutions.conf.franchise substitutions.conf.`uname` > $@
 
 substitutions.conf.local:
 	[ -e $@ ] || \
 	{ ETC_CONF=`sed -n -E -e 's/^ETC_DIR[[:space:]]+(.*)$$/\1/p' substitutions.conf.default | head -n 1`/nodes2grafana.conf ; \
 	  if [ -e $$ETC_CONF ] ; then ln -s $$ETC_CONF $@ ; else touch $@ ; fi ; }
 
-substitutions.conf.default:
-	cp -p substitutions.conf.`uname` substitutions.conf.default
-
 clean:
 	rm -f substitutions.sed substitutions.conf substitutions.conf.default
 	[ -L substitutions.conf.local ] && rm -f substitutions.conf.local || [ -s substitutions.conf.local ] || rm -f substitutions.conf.local