Como monitorar as métricas do Jitsi Videobridge com Prometheus e Grafana

Quando uma reunião do Jitsi começa a apresentar problemas, um administrador pode receber reclamações sobre áudio instável ou vídeo congelado, mas não tem uma maneira rápida de saber se a ponte está sobrecarregada, inacessível ou simplesmente com mais tráfego do que o normal. O Jitsi Videobridge (JVB) expõe métricas operacionais que o Prometheus pode coletar e o Grafana pode exibir. Este guia apresenta uma configuração prática, começando com uma verificação de um endpoint local e terminando com um painel que você pode verificar.

Exemplo de cenário: Imagine uma pequena organização executando um JVB em um host Linux e o Prometheus e o Grafana no mesmo host. Este é um exemplo ilustrativo, não um relato de uma implantação ou teste real. Se seus serviços forem executados em contêineres separados ou em servidores diferentes, substitua os endereços internos acessíveis e mantenha as mesmas restrições de rede.

O que você irá monitorar

A documentação atual do projeto JVB descreve um endpoint Prometheus/OpenMetrics integrado /metricsna interface HTTP privada da ponte. Ele lista estatísticas como conferências ativas, endpoints, taxas de bits de entrada e saída, taxas de pacotes e estresse da ponte. A exposição do Prometheus não contém necessariamente todas as estatísticas disponíveis nos outros formatos de relatório do JVB, portanto, considere o endpoint fornecido pela sua versão instalada como a fonte da verdade. A configuração de referência atualmente habilita o recurso REST do Prometheus e vincula a interface HTTP privada ao loopback; a porta HTTP privada padrão documentada é a 8080. Pacotes e modelos de implantação mais antigos podem apresentar diferenças.

O Prometheus coleta e armazena as séries temporais. O Grafana se conecta ao Prometheus como fonte de dados e consulta essas séries armazenadas. Um exportador Jitsi separado não é necessário para este caminho direto de métricas JVB. Consulte a documentação de estatísticas e endpoints do Prometheus do Jitsi , sua configuração de interface HTTP privada e a configuração de referência . Esses arquivos upstream podem ser alterados; verifique a configuração e a versão instaladas em sua própria ponte antes de aplicar os valores de exemplo.

Passo 1: Confirme se o JVB está fornecendo métricas.

Na máquina JVB, primeiro identifique a configuração ativa. Um pacote comum do Debian ou Ubuntu usa `/etc/ /etc/jitsi/videobridge/jvb.confjvb`, mas o Jitsi observa que o arquivo real é qualquer caminho que seja passado para o processo de ponte. Implantações de contêineres podem montar uma configuração gerada. Não assuma que um arquivo de exemplo seja o que o serviço em execução lê.

Com a porta padrão e a vinculação de loopback do exemplo, execute este comando no host JVB:

curl -fsS http://127.0.0.1:8080/metrics | head

Uma resposta bem-sucedida é um texto simples contendo famílias de métricas do Prometheus, frequentemente com linhas # HELP`& # TYPE` seguidas por amostras. A ilustração mostra apenas o comando; não é evidência de uma resposta real do servidor. Uma recusa de conexão geralmente significa que o JVB está parado, escutando em outro endereço ou porta, ou que a configuração instalada desabilita esse ouvinte HTTP. Um erro HTTP 404 sugere que o servidor respondeu, mas a rota não está disponível nessa versão ou configuração da API. Verifique os logs do JVB e a configuração da sua versão instalada, em vez de habilitar a API de controle do Colibri (que não tem relação com o problema) apenas para fazer o caminho do Prometheus funcionar.

Você pode inspecionar os nomes e tipos de métricas diretamente com:

curl -fsS http://127.0.0.1:8080/metrics | grep -E '^(# HELP|# TYPE)' | head -n 40

A documentação da JVB indica que as métricas disponíveis do Prometheus não são um reflexo completo de suas estatísticas em JSON. Ela também documenta os histogramas de tamanho de conferência disponíveis apenas no formato Prometheus. Verifique o que a sua versão instalada realmente retorna antes de escrever consultas PromQL ou importar um painel que assuma nomes específicos.

Passo 2: Mantenha a interface privada privada

Quando o Prometheus é executado no mesmo host que o JVB, mantenha a interface privada ativada 127.0.0.1. Isso evita a abertura de outro ouvinte para sua rede. Na configuração hipotética de mesmo host, o alvo 127.0.0.1:8080pode ser alcançado diretamente pelo Prometheus.

Se o Prometheus estiver sendo executado em outro local, o vínculo de loopback padrão do JVB não aceitará conexões dele. Você pode configurar o listener privado para se vincular a uma interface interna acessível pelo Prometheus e, em seguida, restringir o firewall ou a rede do contêiner para que somente o host do Prometheus possa se conectar à porta privada. Não exponha as portas 8080 ou 8443 à internet pública: o Jitsi descreve explicitamente essa interface como privada e afirma que seus endpoints não se destinam ao acesso público. Se o ambiente exigir criptografia em trânsito, a interface privada oferece suporte a TLS quando configurada com um keystore; como alternativa, use um proxy TLS interno com controle rigoroso. Evite copiar um vínculo público amplo, como este, 0.0.0.0sem uma restrição de acesso correspondente.

Após alterar uma configuração do listener, utilize o mecanismo de configuração compatível com sua implementação e reinicie ou recarregue o JVB somente quando necessário para aquela versão. Uma reinicialização pode interromper chamadas em uma implementação de ponte única, portanto, agende-a adequadamente. No Docker, edite a configuração persistente do host ou o ambiente usado para gerá-la, e não um arquivo de contêiner transitório. Verifique o listener da máquina Prometheus curlantes de prosseguir.

Etapa 3: Adicione uma tarefa de coleta de dados do Prometheus

Adicione uma tarefa de coleta de dados (scrape job) ao arquivo de configuração do Prometheus. Para o exemplo de mesmo host, a seção relevante é:

scrape_configs:
  - job_name: jitsi-videobridge
    metrics_path: /metrics
    static_configs:
      - targets:
          - 127.0.0.1:8080

A configuração do Prometheus utiliza scrape_configse suporta alvos estáticos para uma pequena implantação fixa. Se o JVB estiver em um contêiner diferente, 127.0.0.1aponte para o próprio contêiner do Prometheus; em vez disso, use o nome e a porta do serviço JVB em uma rede Docker privada compartilhada. Para um host remoto, use seu nome ou endereço DNS privado e mantenha a regra do firewall restrita. A referência de configuração do Prometheus explica os trabalhos de coleta de dados, os alvos e as configurações de intervalo.

Antes de aplicar qualquer alteração, valide o arquivo completo com o utilitário Prometheus fornecido com a sua instalação:

promtool check config /etc/prometheus/prometheus.yml

Se a validação for bem-sucedida, recarregue o Prometheus usando o método configurado para o seu serviço ou reinicie-o caso as recargas não estejam habilitadas. Não considere apenas um arquivo YAML válido como prova de sucesso; um destino sintaticamente válido ainda pode estar inacessível.

Etapa 4: Conecte o Grafana ao Prometheus

No Grafana, adicione a fonte de dados Prometheus integrada e insira a URL que o próprio Grafana consegue acessar. Em um host, isso pode ser o endereço IP http://localhost:9090do Grafana se o Grafana estiver sendo executado diretamente nesse host. Quando o Grafana é executado em um contêiner, localhostrefere-se ao contêiner do Grafana, não ao host ou ao contêiner do Prometheus; use o nome do serviço Prometheus em uma rede compartilhada. Salve e teste a fonte de dados. O guia da fonte de dados Prometheus do Grafana descreve as configurações de conexão, e a documentação da fonte de dados explica como o Grafana consulta um backend de métricas.

Abra o Explorador de Arquivos, selecione Prometheus e execute o comando up{job="jitsi-videobridge"}. Esta é uma verificação de integridade da coleta de dados do Prometheus, não uma métrica do Jitsi. Um valor de 1 significa que o Prometheus coletou os dados do alvo com sucesso para a avaliação atual; 0 significa que um alvo configurado está falhando. Se a consulta não retornar nenhuma série, confirme o nome exato do trabalho, a recarga da configuração, a descoberta do alvo e o intervalo de tempo selecionado.

Etapa 5: Crie um painel de controle útil e verifique os dados.

Após upa verificação de integridade, utilize o navegador de métricas do Grafana Explore ou o navegador de expressões do Prometheus para encontrar as séries JVB expostas pela sua versão. Comece com um pequeno conjunto de perguntas operacionais:

• Quantas conferências e endpoints estão ativos e como esses números variam ao longo do dia?
• As séries temporais de taxa de bits ou de taxa de pacotes RTP de entrada e saída estão mudando conforme a carga da reunião aumenta?
• A série de tensões da ponte aumenta com o número de pontos finais, ou já é alta com uma carga moderada?
• As métricas de threads e coleta de lixo da JVM estão disponíveis e influenciam os relatórios de chamadas lentas?

Use os nomes e unidades das métricas impressas pelo seu próprio /metricsendpoint. A referência de estatísticas do Jitsi descreve exemplos como `max_count` conferences, endpoints`max_count` bit_rate_download, ` bit_rate_uploadmax_count` e ` stress_levelmax_count` na sua lista de estatísticas suportadas, mas alerta que nem todas as estatísticas estão atualmente expostas no formato Prometheus. Não cole esses nomes em uma consulta até confirmar que a família Prometheus existe na sua configuração. Para contadores cumulativos, use funções PromQL como ` rate()count` em um intervalo; para indicadores instantâneos, como a contagem atual de conferências, plote o valor amostrado diretamente. Preserve as unidades documentadas ao rotular os painéis, já que os campos de taxa de bits e as taxas de pacotes usam unidades diferentes.

Crie um painel com alguns gráficos de séries temporais, unidades claras e um intervalo de tempo que inclua as coletas de dados recentes. Evite tratar uma série ausente como zero: a falta de dados pode indicar um erro de digitação, uma métrica não suportada ou uma falha na coleta de dados. Para alertas, comece definindo a disponibilidade desejada e adicione limites somente depois de observar o tráfego normal em sua própria implementação. Um número universal de "alta demanda" pode ser enganoso, pois a capacidade depende do host, da combinação de mídias e da configuração.

Verifique a configuração finalizada.

Execute esta sequência da mais simples para a mais específica:

1. No host JVB, solicite http://127.0.0.1:8080/metricse confirme se a resposta contém o texto da métrica.
2. A partir do host ou contêiner do Prometheus, faça a requisição para o mesmo endpoint usando o endereço privado configurado. Uma requisição bem-sucedida localmente não comprova a acessibilidade remota.
3. Na visualização de Alvos do Prometheus, confirme se o jitsi-videobridgealvo está ativo e verifique o último erro de coleta de dados caso esteja inativo.
4. No Grafana Explore, confirme up{job="jitsi-videobridge"}se o resultado é 1 e, em seguida, consulte o nome de uma métrica JVB copiada do endpoint ativo.
5. Abra um painel de controle abrangendo um intervalo de tempo que inclua vários intervalos de coleta de dados e verifique se as unidades, os rótulos e os registros de data e hora fazem sentido.

Se o endpoint funcionar localmente, mas o Prometheus reportar um erro de conexão, verifique o endereço de vinculação, a porta, o firewall e a rede do contêiner. Se o destino estiver ativo, mas as consultas JVB estiverem vazias, verifique o nome exato exportado, o intervalo de tempo selecionado e se essa estatística está presente na saída do Prometheus. Se os painéis mostrarem dados, mas a qualidade da reunião ainda estiver comprometida, as métricas ajudam a restringir a investigação; elas, por si só, não identificam o problema de Wi-Fi local, navegador ou rede de última milha de um participante.

Esta configuração segue a documentação oficial do Jitsi, Prometheus e Grafana, revisada em 6 de outubro de 2026. Como a configuração de referência do Jitsi e as telas do Grafana estão em constante evolução, compare os exemplos com a documentação e os arquivos das versões exatas que você utiliza.