Conexión de sistemas de monitorización externos

pss-metrics — exportador universal de métricas para Perfect Streamer

Un único script CLI en Python 3 que obtiene las estadísticas de la API HTTP del servidor web PSS y genera la salida para los sistemas de monitorización más habituales:

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

  • Prometheus (formato de exposición de texto para el textfile collector)

  • InfluxDB / Telegraf (line protocol o JSON para el exec input)

  • JSON genérico para scripts propios y comprobaciones de estado de tipo Nagios

El exportador no necesita dependencias de terceros: utiliza solo la biblioteca estándar de Python 3.6+ (urllib, xml.etree, json, argparse).

Archivos

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

Instalación

El exportador se suministra en /opt/pss/monitoring/pss-metrics.py. Asegúrese de que esté instalado Python 3.6 o posterior:

# RHEL / Rocky / AlmaLinux
yum install -y python3

# Debian / Ubuntu
apt-get install -y python3

No se requieren paquetes adicionales.

Configuración

De forma predeterminada, pss-metrics se conecta al nodo por la dirección de loopback y determina el puerto del servidor web a partir de /opt/pss/config/pss.json. Si ese archivo se puede leer, es el que decide: el puerto se toma de su clave web-server.bind-port y, sin esa clave, es 43971, el valor integrado del servicio. El archivo /opt/pss/config/pss_default.json solo se lee si no existe pss.json; si no se ha podido leer el puerto de ninguno de los dos archivos, se utiliza http://127.0.0.1:43971. Con el indicador -v, el exportador informa de qué archivo se tomó el puerto. Los parámetros se pueden redefinir mediante variables de entorno, el archivo /etc/pss-metrics.conf (formato clave=valor) o indicadores de la línea de comandos. Prioridad: CLI > env > archivo > valores predeterminados. PSS_URL, definido por cualquiera de estas vías, desactiva la detección automática del puerto. Antes de la versión 2.0.2.421, PSS_URL del archivo no desactivaba la detección, y un pss.json sin clave de puerto llevaba al puerto 8808 de pss_default.json.

Desde la versión 2.0.2.420, pss.json solo lo puede leer el usuario del servicio pss (el archivo contiene contraseñas). Un exportador que se ejecute con otro usuario (zabbix, telegraf) no puede leer el puerto del archivo y se conecta al puerto 43971; si el servidor web del nodo funciona en otro puerto, defina PSS_URL.

Variables admitidas:

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

Caché: cada ejecución realiza como máximo una petición HTTP GET por punto final dentro de la ventana del TTL. Con TTL=10 s, incluso cientos de comprobaciones de UserParameter por minuto generan unas 6 peticiones HTTP por minuto a cada punto final de la API.

Inicio rápido

Comprobación de estado (códigos de salida de tipo Nagios):

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

Detección LLD de Zabbix:

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

Obtención de una única métrica (para su uso en un UserParameter de 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

Exportación completa:

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

Rutas de las métricas

pss-metrics get acepta una ruta separada por puntos. Una salida vacía significa «valor ausente» (por ejemplo, la métrica solo existe para los flujos en ejecución).

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

Atributos útiles por flujo (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

Las velocidades se indican en kilobits por segundo: speed1 en la entrada, speed en la salida. El atributo speed solo existe en las salidas UDP; en los demás tipos de salida la velocidad se deduce del incremento de sent-bytes durante el propio intervalo de sondeo.

Integración con Zabbix

Se admiten dos escenarios: elija el que se adapte a su entorno.

  1. UserParameter estático + LLD (Zabbix agent v1 / v2)

    Copie userparameter_pss.conf.example en /etc/zabbix/zabbix_agentd.d/pss.conf, reinicie zabbix-agent e importe en el servidor una plantilla con prototipos LLD que utilicen las claves pss.discover. Ejemplo de vinculaciones:

    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

    En el servidor 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) mediante zabbix_sender

    Ejecútelo con un temporizador (cron / systemd) y redirija la salida a una tubería:

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

Integración con Prometheus

Dos opciones.

  1. Textfile collector (recomendado para entornos de ejecución puntual).

    Ejecute una exportación periódica mediante un temporizador de systemd o 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 entregará el archivo mediante –collector.textfile.directory.

  2. Scrape directo a través de un pequeño envoltorio (por ejemplo, socat + pss-metrics dump) o de cualquier proxy HTTP de terceros que prefiera.

Integración con Telegraf / InfluxDB

Telegraf inputs.exec:

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

Para el analizador JSON, utilice –format=json y configure data_format = «json» indicando las rutas a los campos.

HTTPS y autenticación

El exportador está previsto para ejecutarse en el propio nodo: el servidor web PSS acepta sin autorización las peticiones procedentes de la dirección local. Las variables PSS_USER/PSS_PASS se transmiten como HTTP Basic; resultan útiles cuando el acceso a la API se publica a través de un proxy intermedio con autorización Basic. El exportador no admite la autorización Digest propia del servidor web PSS.

Acceso por HTTPS:

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

Certificados autofirmados: establezca PSS_INSECURE=1 (no recomendado) o indique PSS_CA_BUNDLE=/path/to/ca.pem.

Códigos de salida

pss-metrics sigue la convención de Nagios:

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

get imprime una cadena vacía y termina con el código 0 si la entidad solicitada no existe: Zabbix interpreta un valor vacío como «NOT_SUPPORTED» y no como un fallo del agente.

Diagnóstico

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