--- title: Ligação de sistemas de monitorização externos url: https://doc2.pstreamer.tv/pt/manual/extras/monitoring.html lang: pt-BR product: Perfect Streamer version: 2.0.2.362 --- # 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= ``` 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. e.g. server.server-version, server.uptime summary. total | running | stopped | unhealthy | input_bitrate_kbps | output_bitrate_kbps sysmon.cpu. self-usage | total-usage | cores sysmon.memory. self-usage-kb | available-kb | total-kb sysmon.netbw.. rx-bw | tx-bw (interface name as in XML) stream.. any attribute input... any attribute output... any 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 ``` As taxas estão em kilobits por segundo: `speed1` na entrada, `speed` na saída. O atributo `speed` existe apenas nas saídas UDP; nos demais tipos de saída a taxa é deduzida do incremento de `sent-bytes` durante o seu próprio intervalo de consulta. ## Integração com o Zabbix São suportados dois cenários — escolha o que se adequa ao seu ambiente. 1. 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] ``` 2. 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. 1. 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*. 2. 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: ``` 0 OK 1 WARNING (e.g. running streams report unhealthy) 2 CRITICAL (PSS is unreachable) 3 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 ```bash 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 ```