Ligação de sistemas de monitorização externos¶

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

Um único script CLI em Python 3 que obtém as estatísticas a partir da API HTTP do servidor web PSS e gera a saída para os sistemas de monitorização mais divulgados:

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

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

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

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

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

Ficheiros¶

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

Instalação¶

O exportador é fornecido em /opt/pss/monitoring/pss-metrics.py. Certifique-se de que está instalado o Python 3.6 ou posterior:

# RHEL / Rocky / AlmaLinux
yum install -y python3

# Debian / Ubuntu
apt-get install -y python3

Não são necessários pacotes adicionais.

Configuração¶

Por padrão, o pss-metrics conecta-se ao nó pelo endereço de loopback, determinando a porta do servidor web a partir de /opt/pss/config/pss.json (ou de /opt/pss/config/pss_default.json); se a porta não puder ser lida de nenhum dos arquivos, é usado http://127.0.0.1:43971. Os parâmetros podem ser substituídos através de variáveis de ambiente, do arquivo /etc/pss-metrics.conf (formato chave=valor) ou de opções da linha de comando. Prioridade: CLI > env > arquivo > valores padrão. A exceção é PSS_URL: o valor lido do arquivo pode ser substituído pela detecção automática da porta; defina o URL através de uma variável de ambiente ou de uma opção da linha de comando.

Variáveis suportadas:

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: cada execução efetua no máximo um HTTP GET por ponto final dentro da janela do TTL. Com TTL=10 s, mesmo centenas de verificações UserParameter por minuto resultam em cerca de 6 pedidos HTTP por minuto para cada ponto final da API.

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=<versão>

Deteção 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 utilizar num 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¶

O pss-metrics get aceita um caminho separado por pontos. Uma saída vazia significa «valor inexistente» (por exemplo, a métrica só existe para os 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 (a partir 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 o Zabbix¶

São suportados dois cenários — escolha o que se adequa ao seu ambiente.

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

Copie userparameter_pss.conf.example para /etc/zabbix/zabbix_agentd.d/pss.conf, reinicie o zabbix-agent e importe no servidor um modelo com protótipos LLD que utilizem as chaves pss.discover. Exemplo 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) através do zabbix_sender

Execute por temporizador (cron / systemd) e encaminhe 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 o Prometheus¶

Duas opções.

Textfile collector (recomendado para ambientes one-shot).

Execute uma exportação periódica através de um temporizador do systemd ou do 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 através de –collector.textfile.directory.

Scrape direto através de um pequeno invólucro (por exemplo, socat + pss-metrics dump) ou de qualquer proxy HTTP de terceiros à sua escolha.

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

HTTPS e autenticação¶

O exportador destina-se a ser executado no próprio nó: o servidor web PSS aceita sem autorização os pedidos provenientes do endereço local. As variáveis PSS_USER/PSS_PASS são transmitidas como HTTP Basic — são úteis quando o acesso à API é publicado através de um proxy intermédio com autorização Basic; o exportador não passa a autorização Digest própria do servidor web PSS.

Acesso por HTTPS:

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

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

Códigos de saída¶

O 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)

O get imprime uma cadeia vazia e termina com o código 0 se a entidade solicitada não existir — o que corresponde à expectativa do Zabbix de que um valor vazio é interpretado como «NOT_SUPPORTED» e não como uma 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