--- title: Anbindung externer Überwachungssysteme url: https://doc2.pstreamer.tv/de/manual/extras/monitoring.html lang: de product: Perfect Streamer version: 2.0.2.362 --- # Anbindung externer Überwachungssysteme *pss-metrics* — universeller Metrik-Exporter für Perfect Streamer Ein einzelnes CLI-Skript in Python 3, das Statistiken über die HTTP-API des PSS-Webservers abruft und daraus Ausgaben für die gängigsten Überwachungssysteme erzeugt: > - Zabbix (UserParameter, Low-Level Discovery, zabbix_sender trapper) > - Prometheus (Text-Expositionsformat für den textfile collector) > - InfluxDB / Telegraf (line protocol oder JSON für den exec input) > - Generisches JSON für beliebige Skripte und Zustandsprüfungen im Nagios-Stil Der Exporter ist eine einzelne, eigenständige Datei ohne Fremdabhängigkeiten; er verwendet ausschließlich die Standardbibliothek von Python 3.6+ (*urllib*, *xml.etree*, *json*, *argparse*). ## Dateien ``` pss-metrics.py main CLI (executable) userparameter_pss.conf.example UserParameter template for Zabbix ``` ## Installation Der Exporter wird als */opt/pss/monitoring/pss-metrics.py* ausgeliefert. Stellen Sie sicher, dass Python 3.6 oder neuer installiert ist: ``` # RHEL / Rocky / AlmaLinux yum install -y python3 # Debian / Ubuntu apt-get install -y python3 ``` Zusätzliche Pakete sind nicht erforderlich. ## Konfiguration Standardmäßig verbindet sich *pss-metrics* über die Loopback-Adresse mit dem Knoten und ermittelt den Port des Webservers aus */opt/pss/config/pss.json* (oder */opt/pss/config/pss_default.json*); lässt sich der Port aus keiner der beiden Dateien lesen, wird *http://127.0.0.1:43971* verwendet. Die Parameter lassen sich über Umgebungsvariablen, die Datei */etc/pss-metrics.conf* (Format *Schlüssel=Wert*) oder Kommandozeilenflags überschreiben. Priorität: CLI > env > Datei > Standardwerte. Ausnahme ist *PSS_URL*: Ein Wert aus der Datei kann durch die automatische Porterkennung überschrieben werden; setzen Sie die URL daher über eine Umgebungsvariable oder ein Kommandozeilenflag. Unterstützte Variablen: ``` PSS_URL full URL, e.g. http://10.0.0.1:8808 (auto by default) PSS_USER web server login (if authorization is enabled) PSS_PASS web server password PSS_TIMEOUT HTTP timeout, in seconds (default 5) PSS_CACHE_DIR cache directory (default /run/pss-metrics) PSS_CACHE_TTL cache TTL, in seconds (default 10) PSS_CA_BUNDLE path to CA bundle for HTTPS PSS_INSECURE 1 — disable TLS certificate verification PSS_VERBOSE 1 — log requests to stderr ``` Cache: Jeder Lauf führt innerhalb des TTL-Fensters höchstens ein HTTP GET pro Endpunkt aus. Bei TTL=10 s ergeben selbst Hunderte von UserParameter-Prüfungen pro Minute nur etwa 6 HTTP-Anfragen pro Minute an jeden API-Endpunkt. ## Schnellstart Zustandsprüfung (exit codes im Nagios-Stil): ``` pss-metrics.py health # OK: total=42 running=15 stopped=27 unhealthy=0 version= ``` Zabbix-LLD-Erkennung: ``` pss-metrics.py discover streams pss-metrics.py discover inputs --running-only pss-metrics.py discover outputs ``` Abruf einer einzelnen Metrik (zur Verwendung in einem Zabbix-UserParameter): ``` pss-metrics.py get summary.running pss-metrics.py get stream.10031.bitrate pss-metrics.py get input.10031.1.speed1 pss-metrics.py get output.10031.1.speed pss-metrics.py get sysmon.cpu.self-usage pss-metrics.py get server.server-version ``` Vollständiger Export: ``` pss-metrics.py dump --format=json pss-metrics.py dump --format=prometheus pss-metrics.py dump --format=influx pss-metrics.py dump --format=zabbix-trapper --zabbix-host=streamer-01 ``` ## Metrikpfade *pss-metrics get* erwartet einen durch Punkte getrennten Pfad. Eine leere Ausgabe bedeutet „kein Wert“ (die Metrik existiert beispielsweise nur für laufende Streams). ``` server. e.g. server.server-version, server.uptime summary. total | running | stopped | unhealthy | input_bitrate_kbps | output_bitrate_kbps sysmon.cpu. self-usage | total-usage | cores sysmon.memory. self-usage-kb | available-kb | total-kb sysmon.netbw.. rx-bw | tx-bw (interface name as in XML) stream.. any attribute input... any attribute output... any attribute ``` Nützliche Attribute je Stream (aus /data/stream/detail): ``` stream: state, state-str, bitrate, thread-usage, mpts input: speed1, recv-bytes, recv-packets, recv-err, stat-disc, stat-disc1, stat-scrambled, stat-scrambled1, health-state-good, health-status, check-status output: speed, sent-bytes, sent-packets, sent-err, uri, type ``` Die Raten sind in Kilobit pro Sekunde angegeben: `speed1` beim Eingang, `speed` beim Ausgang. Das Attribut `speed` gibt es nur bei UDP-Ausgängen; bei den übrigen Ausgangstypen wird die Rate aus dem Zuwachs von `sent-bytes` über das eigene Abfrageintervall abgeleitet. ## Integration mit Zabbix Es werden zwei Szenarien unterstützt — wählen Sie das für Ihre Umgebung passende aus. 1. Statischer UserParameter + LLD (Zabbix agent v1 / v2) Kopieren Sie *userparameter_pss.conf.example* nach */etc/zabbix/zabbix_agentd.d/pss.conf*, starten Sie *zabbix-agent* neu und importieren Sie auf dem Server eine Vorlage mit LLD-Prototypen, die die Schlüssel *pss.discover* verwenden. Beispiel für Zuordnungen: ``` UserParameter=pss.discover[*],/opt/pss/monitoring/pss-metrics.py discover $1 UserParameter=pss.get[*],/opt/pss/monitoring/pss-metrics.py get $1 UserParameter=pss.health,/opt/pss/monitoring/pss-metrics.py health ``` Auf dem Zabbix-Server: ``` Discovery rule key: pss.discover[streams] Item prototype keys: pss.get[input.{#STREAM_ID}.1.speed1] pss.get[stream.{#STREAM_ID}.bitrate] pss.get[summary.unhealthy] ``` 2. Trapper (push) über zabbix_sender Führen Sie den Aufruf zeitgesteuert aus (cron / systemd) und leiten Sie die Ausgabe in eine Pipe: ``` /opt/pss/monitoring/pss-metrics.py dump --format=zabbix-trapper \ --zabbix-host="$(hostname)" \ | zabbix_sender -z zabbix.example.com -i - ``` ## Integration mit Prometheus Zwei Varianten. 1. Textfile collector (empfohlen für One-shot-Umgebungen). Führen Sie den Export periodisch über einen systemd-Timer oder cron aus: ``` */1 * * * * /opt/pss/monitoring/pss-metrics.py dump --format=prometheus \ > /var/lib/node_exporter/textfile_collector/pss.prom.$$ \ && mv /var/lib/node_exporter/textfile_collector/pss.prom.$$ \ /var/lib/node_exporter/textfile_collector/pss.prom ``` *node_exporter* liefert die Datei über *–collector.textfile.directory* aus. 2. Direktes Scraping über einen kleinen Wrapper (zum Beispiel *socat* + *pss-metrics dump*) oder über einen beliebigen HTTP-Proxy eines Drittanbieters Ihrer Wahl. ## Integration mit Telegraf / InfluxDB Telegraf *inputs.exec*: ``` [[inputs.exec]] commands = ["/opt/pss/monitoring/pss-metrics.py dump --format=influx"] interval = "10s" timeout = "5s" data_format = "influx" ``` Für den JSON-Parser verwenden Sie *–format=json* und konfigurieren *data_format = „json“* unter Angabe der Feldpfade. ## HTTPS und Authentifizierung Der Exporter ist für den Betrieb auf dem Knoten selbst ausgelegt: Anfragen von der lokalen Adresse nimmt der PSS-Webserver ohne Autorisierung entgegen. Die Variablen *PSS_USER*/*PSS_PASS* werden als HTTP Basic übergeben — sie sind nützlich, wenn der Zugriff auf die API über einen vorgelagerten Proxy mit Basic-Autorisierung veröffentlicht wird; die eigene Digest-Autorisierung des PSS-Webservers durchläuft der Exporter nicht. Zugriff über HTTPS: ``` PSS_URL=https://streamer.example.com:43981 pss-metrics.py health ``` Selbstsignierte Zertifikate: Setzen Sie *PSS_INSECURE=1* (nicht empfohlen) oder geben Sie *PSS_CA_BUNDLE=/path/to/ca.pem* an. ## Rückgabecodes *pss-metrics* folgt der Nagios-Konvention: ``` 0 OK 1 WARNING (e.g. running streams report unhealthy) 2 CRITICAL (PSS is unreachable) 3 UNKNOWN (invalid arguments / internal error) ``` *get* gibt eine leere Zeile aus und endet mit dem Code 0, wenn die angeforderte Entität nicht vorhanden ist — das entspricht der Erwartung von Zabbix, dass ein leerer Wert als „NOT_SUPPORTED“ und nicht als Ausfall des Agenten gewertet wird. ## Diagnose ```bash pss-metrics.py -v health # log every HTTP request to stderr pss-metrics.py --cache-ttl=0 … # bypass cache while debugging rm -rf /run/pss-metrics # purge cache ```