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 n’a besoin d’aucune dépendance tierce : 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. Si ce fichier est lisible, c’est lui qui décide : le port est tiré de sa clé web-server.bind-port et, sans cette clé, vaut 43971, la valeur intégrée du service. Le fichier /opt/pss/config/pss_default.json n’est lu que s’il n’y a pas de pss.json ; si le port n’a pu être lu dans aucun des deux fichiers, http://127.0.0.1:43971 est utilisé. Avec l’option -v, l’exportateur indique de quel fichier le port a été tiré. 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. PSS_URL, défini par l’un de ces moyens, désactive la détection automatique du port. Avant la version 2.0.2.421, PSS_URL issu du fichier ne désactivait pas la détection, et un pss.json sans clé de port menait au port 8808 de pss_default.json.

Depuis la version 2.0.2.420, pss.json n’est lisible que par l’utilisateur du service pss (le fichier contient des mots de passe). Un exportateur lancé sous un autre utilisateur (zabbix, telegraf) ne peut pas lire le port dans le fichier et se connecte au port 43971 ; si le serveur web du nœud fonctionne sur un autre port, définissez PSS_URL.

Variables prises en charge:

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 : 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

Les débits sont indiqués en kilobits par seconde : speed1 pour l”entrée, speed pour la sortie. L’attribut speed n’existe que sur les sorties UDP ; pour les autres types de sortie, le débit se déduit de l’accroissement de sent-bytes sur votre propre intervalle d’interrogation.

Intégration avec Zabbix

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

  1. 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]

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

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

  2. Scrape direct au moyen d’un petit script intermédiaire (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 prend pas en charge 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:

0  OK
1  WARNING       (e.g. running streams report unhealthy)
2  CRITICAL      (PSS is unreachable)
3  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 : Zabbix interprète une valeur vide 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