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 braucht keine 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. Lässt sich diese Datei lesen, entscheidet sie: Der Port kommt aus ihrem Schlüssel web-server.bind-port, ohne diesen Schlüssel ist es 43971, der eingebaute Wert des Dienstes. Die Datei /opt/pss/config/pss_default.json wird nur gelesen, wenn es keine pss.json gibt; lässt sich der Port aus keiner der beiden Dateien lesen, wird http://127.0.0.1:43971 verwendet. Mit dem Flag -v meldet der Exporter, aus welcher Datei der Port stammt. 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. Ein auf einem dieser Wege gesetztes PSS_URL schaltet die automatische Porterkennung ab. Vor Version 2.0.2.421 schaltete PSS_URL aus der Datei die Erkennung nicht ab, und eine pss.json ohne Port-Schlüssel führte zum Port 8808 aus pss_default.json.

Ab Version 2.0.2.420 kann nur der Dienstbenutzer pss die Datei pss.json lesen (sie enthält Passwörter). Ein Exporter, der unter einem anderen Benutzer läuft (zabbix, telegraf), kann den Port nicht aus der Datei lesen und verbindet sich mit Port 43971; läuft der Webserver des Knotens auf einem anderen Port, setzen Sie PSS_URL.

Unterstützte Variablen:

PSS_URL          full URL, e.g. http://10.0.0.1:8808          (auto by default)
PSS_USER         login sent as HTTP Basic (for a proxy in front of PSS, see below)
PSS_PASS         password for PSS_USER
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

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.

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 Sie data_format = „json“ mit den Pfaden zu den Feldern.

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: Zabbix wertet einen leeren Wert als „NOT_SUPPORTED“ und nicht als Ausfall des Agenten.

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