|
|
@@ -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.
|
|
|
|
