Connexion de systèmes de supervision externes¶

pss-metrics — exportateur universel de métriques pour Perfect Streamer

Un unique script CLI en Python 3 qui récupère les statistiques depuis l’API HTTP du serveur web PSS et produit une sortie destinée aux systèmes de supervision les plus répandus :

Zabbix (UserParameter, Low-Level Discovery, zabbix_sender trapper)

Prometheus (format d’exposition texte pour le textfile collector)

InfluxDB / Telegraf (line protocol ou JSON pour l’entrée exec)

JSON générique pour des scripts personnalisés et des contrôles d’état de type Nagios

L’exportateur est un fichier unique et autonome, sans dépendances tierces ; il n’utilise que la bibliothèque standard de Python 3.6+ (urllib, xml.etree, json, argparse).

Fichiers¶

pss-metrics.py                    main CLI (executable)
userparameter_pss.conf.example    UserParameter template for Zabbix

Installation¶

L’exportateur est fourni dans /opt/pss/monitoring/pss-metrics.py. Assurez-vous que Python 3.6 ou une version ultérieure est installé:

# RHEL / Rocky / AlmaLinux
yum install -y python3

# Debian / Ubuntu
apt-get install -y python3

Aucun paquet supplémentaire n’est requis.

Configuration¶

Par défaut, pss-metrics se connecte au nœud par l’adresse de bouclage en déterminant le port du serveur web à partir de /opt/pss/config/pss.json (ou de /opt/pss/config/pss_default.json) ; si le port n’a pu être lu dans aucun des deux fichiers, http://127.0.0.1:43971 est utilisé. Les paramètres peuvent être redéfinis par des variables d’environnement, par le fichier /etc/pss-metrics.conf (format clé=valeur) ou par des options de ligne de commande. Priorité : CLI > env > fichier > valeurs par défaut. Exception — PSS_URL : la valeur issue du fichier peut être remplacée par la détection automatique du port ; définissez l’URL au moyen d’une variable d’environnement ou d’une option de ligne de commande.

Variables prises en charge:

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 : chaque exécution effectue au plus un GET HTTP par point de terminaison dans la fenêtre de TTL. Avec TTL=10 s, même des centaines de contrôles UserParameter par minute ne produisent qu’environ 6 requêtes HTTP par minute vers chaque point de terminaison de l’API.

Démarrage rapide¶

Contrôle d’état (codes de sortie de type Nagios):

pss-metrics.py health
# OK: total=42 running=15 stopped=27 unhealthy=0 version=<version>

Découverte LLD Zabbix:

pss-metrics.py discover streams
pss-metrics.py discover inputs --running-only
pss-metrics.py discover outputs

Récupération d’une métrique unique (à utiliser dans un UserParameter Zabbix):

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

Export complet:

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

Chemins de métriques¶

pss-metrics get accepte un chemin séparé par des points. Une sortie vide signifie « valeur absente » (par exemple, la métrique n’existe que pour les flux en cours d’exécution).

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

Attributs utiles par flux (issus de /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

Intégration avec Zabbix¶

Deux scénarios sont pris en charge — choisissez celui qui convient à votre environnement.

UserParameter statique + LLD (agent Zabbix v1 / v2)

Copiez userparameter_pss.conf.example vers /etc/zabbix/zabbix_agentd.d/pss.conf, redémarrez zabbix-agent, puis importez sur le serveur un modèle comportant des prototypes LLD qui utilisent les clés pss.discover. Exemple d’associations:

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

Sur le serveur Zabbix :

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) au moyen de zabbix_sender

Lancez-le par minuterie (cron / systemd) et redirigez la sortie dans un pipe:

/opt/pss/monitoring/pss-metrics.py dump --format=zabbix-trapper \
    --zabbix-host="$(hostname)" \
  | zabbix_sender -z zabbix.example.com -i -

Intégration avec Prometheus¶

Deux options.

Textfile collector (recommandé pour les environnements one-shot).

Lancez un export périodique au moyen d’un systemd-timer ou de cron:

*/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 publiera le fichier au moyen de –collector.textfile.directory.

Scrape direct au moyen d’un petit enrobage (par exemple, socat + pss-metrics dump) ou de tout proxy HTTP tiers de votre choix.

Intégration avec Telegraf / InfluxDB¶

Telegraf inputs.exec:

[[inputs.exec]]
  commands = ["/opt/pss/monitoring/pss-metrics.py dump --format=influx"]
  interval = "10s"
  timeout  = "5s"
  data_format = "influx"

Pour l’analyseur JSON, utilisez –format=json et configurez data_format = « json » en indiquant les chemins des champs.

HTTPS et authentification¶

L’exportateur est prévu pour s’exécuter sur le nœud lui-même : le serveur web PSS accepte sans autorisation les requêtes provenant de l’adresse locale. Les variables PSS_USER/PSS_PASS sont transmises en HTTP Basic — elles sont utiles lorsque l’accès à l’API est publié au travers d’un proxy intermédiaire doté d’une autorisation Basic ; l’exportateur ne satisfait pas l’autorisation Digest propre au serveur web PSS.

Accès en HTTPS:

PSS_URL=https://streamer.example.com:43981 pss-metrics.py health

Certificats auto-signés : définissez PSS_INSECURE=1 (non recommandé) ou indiquez PSS_CA_BUNDLE=/path/to/ca.pem.

Codes de retour¶

pss-metrics respecte la convention Nagios:

OK
WARNING       (e.g. running streams report unhealthy)
CRITICAL      (PSS is unreachable)
UNKNOWN       (invalid arguments / internal error)

get affiche une chaîne vide et se termine avec le code 0 lorsque l’entité demandée est absente — ce comportement correspond à l’attente de Zabbix, selon laquelle une valeur vide est interprétée comme « NOT_SUPPORTED » et non comme une défaillance de l’agent.

Diagnostic¶

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