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 es un único archivo autónomo sin 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 (o de /opt/pss/config/pss_default.json); si no se ha podido leer el puerto de ninguno de los dos archivos, se utiliza http://127.0.0.1:43971. 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 es la excepción: el valor tomado del archivo puede ser sustituido por la detección automática del puerto; defina la URL mediante una variable de entorno o un indicador de la línea de comandos.

Variables admitidas:

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

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

Integración con Zabbix¶

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

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]

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.

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.

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

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

get imprime una cadena vacía y termina con el código 0 si la entidad solicitada no existe; esto se corresponde con la expectativa de Zabbix de que un valor vacío se interprete 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