Integração de sistemas externos de monitoramento¶

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

Um único script CLI em Python 3 que obtém estatísticas da API HTTP do servidor web do PSS e gera saída para os sistemas de monitoramento mais comuns:

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

Prometheus (formato de exposição de texto para o textfile collector)

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

JSON universal para scripts arbitrários e verificações de estado no estilo Nagios

O exportador é um arquivo único e autocontido, sem dependências de terceiros, e usa apenas a biblioteca padrão do Python 3.6+ (urllib, xml.etree, json, argparse).

Arquivos¶

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

Instalação¶

O exportador é entregue em /opt/pss/monitoring/pss-metrics.py. Verifique se o Python 3.6 ou posterior está instalado:

# RHEL / Rocky / AlmaLinux
yum install -y python3

# Debian / Ubuntu
apt-get install -y python3

Nenhum pacote adicional é necessário.

Configuração¶

Por padrão, pss-metrics conecta-se a http://127.0.0.1:43971 e detecta automaticamente a porta a partir de /opt/pss/config/pss.json (ou /opt/pss/config/pss_default.json). Os parâmetros podem ser sobrepostos por variáveis de ambiente, pelo arquivo /etc/pss-metrics.conf (formato chave=valor) ou por flags de linha de comando. Prioridade: CLI > env > arquivo > valores padrão.

Variáveis suportadas:

PSS_URL          full URL, e.g. http://10.0.0.1:43971         (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: cada execução faz no máximo um HTTP GET por endpoint dentro da janela de TTL. Com TTL=10 s, mesmo centenas de verificações de UserParameter por minuto resultam em ~6 requisições HTTP por minuto ao PSS.

Início rápido¶

Verificação de estado (códigos de saída no estilo Nagios):

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

Descoberta LLD do Zabbix:

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

Obtenção de uma única métrica (para uso em UserParameter do 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

Exportação 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

Caminhos das métricas¶

pss-metrics get aceita um caminho separado por pontos. Saída vazia significa «valor ausente» (por exemplo, a métrica só existe para fluxos em execução).

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 úteis por fluxo (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

Integração com Zabbix¶

Dois cenários são suportados — escolha o que se adequa ao seu ambiente.

UserParameter estático + LLD (agente Zabbix v1 / v2)

Copie userparameter_pss.conf.example para /etc/zabbix/zabbix_agentd.d/pss.conf, reinicie o zabbix-agent e importe no servidor um template com protótipos LLD que utilizem as chaves pss.discover. Exemplos de associações:

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

No 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) por zabbix_sender

Execute por temporizador (cron / systemd) e direcione a saída para um pipe:

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

Integração com Prometheus¶

Duas opções.

Textfile collector (recomendado para ambientes one-shot).

Execute uma exportação periódica via systemd-timer ou 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

O node_exporter disponibiliza o arquivo via –collector.textfile.directory.

Scrape direto por meio de um pequeno wrapper (por exemplo socat + pss-metrics dump) ou qualquer proxy HTTP de terceiros à sua escolha.

Integração com 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 o parser JSON, use –format=json e configure data_format = «json» com os caminhos dos campos.

HTTPS e autenticação¶

Se o servidor web do PSS opera atrás de HTTPS ou é protegido por senha:

PSS_URL=https://streamer.example.com:8443 \
PSS_USER=monitor PSS_PASS=secret \
pss-metrics.py health

Certificados autoassinados: defina PSS_INSECURE=1 (não recomendado) ou informe PSS_CA_BUNDLE=/path/to/ca.pem.

Códigos de saída¶

pss-metrics segue a convenção do Nagios:

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

get e dump produzem uma linha vazia e encerram com código 0 quando a entidade solicitada está ausente — isso corresponde à expectativa do Zabbix de que um valor vazio seja tratado como «NOT_SUPPORTED» e não como falha do 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