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=<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.<attr>                e.g. server.server-version, server.uptime
summary.<key>                total | running | stopped | unhealthy |
                             input_bitrate_kbps | output_bitrate_kbps
sysmon.cpu.<attr>            self-usage | total-usage | cores
sysmon.memory.<attr>         self-usage-kb | available-kb | total-kb
sysmon.netbw.<iface>.<attr>  rx-bw | tx-bw  (interface name as in XML)
stream.<id>.<attr>           any <stream> attribute
input.<sid>.<iid>.<attr>     any <input> attribute
output.<sid>.<oid>.<attr>    any <output> 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

Integration mit Zabbix¶

Es werden zwei Szenarien unterstützt — wählen Sie das für Ihre Umgebung passende aus.

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]

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.

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.

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:

OK
WARNING       (e.g. running streams report unhealthy)
CRITICAL      (PSS is unreachable)
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¶

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