Comment surveiller les indicateurs de Jitsi Videobridge avec Prometheus et Grafana

Lorsqu'une réunion Jitsi présente des problèmes de fluidité, un administrateur peut recevoir des plaintes concernant des coupures audio ou des images figées, sans pouvoir déterminer rapidement si le pont est surchargé, inaccessible ou simplement soumis à un trafic inhabituel. Jitsi Videobridge (JVB) expose des indicateurs de performance que Prometheus peut collecter et que Grafana peut afficher. Ce guide décrit une configuration pratique, depuis la vérification du point de terminaison local jusqu'à la création d'un tableau de bord vérifiable.

Exemple de scénario : Imaginez une petite organisation exécutant une instance JVB sur un serveur Linux, ainsi que Prometheus et Grafana sur ce même serveur. Il s’agit d’un exemple illustratif, et non d’un compte rendu de déploiement ou de test réel. Si vos services s’exécutent dans des conteneurs distincts ou sur des serveurs différents, veuillez remplacer leurs adresses internes accessibles et conserver les mêmes restrictions réseau.

Ce que vous surveillerez

La documentation actuelle du projet JVB décrit un point de terminaison Prometheus/OpenMetrics intégré à /metricsl'interface HTTP privée du pont. Ce point de terminaison affiche des statistiques telles que les conférences actives, les points de terminaison, les débits entrants et sortants, les débits de paquets et la charge du pont. Les données fournies par Prometheus ne contiennent pas nécessairement toutes les statistiques disponibles via les autres formats de rapport de JVB ; par conséquent, considérez le point de terminaison fourni par votre version installée comme la source de référence. La configuration de référence active actuellement la ressource REST Prometheus et lie l'interface HTTP privée à l'interface de bouclage (boucle locale). Le port HTTP privé par défaut documenté est le 8080. Les versions plus anciennes et les modèles de déploiement peuvent différer.

Prometheus collecte et stocke les séries temporelles. Grafana se connecte à Prometheus comme source de données et interroge ces séries stockées. Un exportateur Jitsi distinct n'est pas nécessaire pour cette méthode directe d'accès aux métriques JVB. Consultez la documentation relative aux statistiques et au point de terminaison Prometheus de Jitsi , la configuration de son interface HTTP privée et la configuration de référence . Ces fichiers en amont peuvent être modifiés ; vérifiez la configuration et la version installées sur votre propre serveur avant d'appliquer les valeurs d'exemple.

Étape 1 : Vérifier que JVB fournit des métriques

Sur la machine JVB, commencez par identifier la configuration active. Un paquet Debian ou Ubuntu courant utilise `.jv` /etc/jitsi/videobridge/jvb.conf, mais Jitsi précise que le fichier réel correspond au chemin transmis au processus de pont. Les déploiements de conteneurs peuvent monter une configuration générée. Ne présumez pas qu'un fichier d'exemple soit celui utilisé par le service en cours d'exécution.

Avec le port par défaut et la liaison de bouclage de l'exemple, exécutez cette commande sur l'hôte JVB :

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

Une réponse positive est un texte brut contenant les familles de métriques Prometheus, souvent avec # HELPdes # TYPElignes suivies d'exemples. L'illustration montre uniquement la commande ; elle ne constitue pas une preuve de réponse du serveur. Un refus de connexion signifie généralement que JVB est arrêté, qu'il écoute sur une autre adresse ou un autre port, ou que la configuration installée désactive cet écouteur HTTP. Une erreur HTTP 404 indique que le serveur a répondu, mais que la route est indisponible dans cette version ou cette configuration d'API. Consultez les journaux JVB et la configuration de votre version installée plutôt que d'activer l'API de contrôle Colibri (sans rapport avec le problème) simplement pour que le chemin Prometheus fonctionne.

Vous pouvez inspecter directement les noms et les types de métriques avec :

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

JVB indique que les métriques Prometheus disponibles ne reflètent pas intégralement ses statistiques JSON. Il précise également que les histogrammes de taille de conférence ne sont disponibles qu'au format Prometheus. Vérifiez le format de retour de votre version installée avant d'écrire des requêtes PromQL ou d'importer un tableau de bord utilisant des noms spécifiques.

Étape 2 : Préserver la confidentialité de l’interface privée

Lorsque Prometheus s'exécute sur le même hôte que JVB, laissez l'interface privée activée 127.0.0.1. Cela évite d'ouvrir un autre écouteur sur votre réseau. Dans cette configuration hypothétique où les deux hôtes sont utilisés, la cible 127.0.0.1:8080est directement accessible par Prometheus.

Si Prometheus s'exécute ailleurs, la liaison de bouclage par défaut de JVB refusera les connexions provenant de celui-ci. Vous pouvez configurer l'écouteur privé pour qu'il se lie à une interface interne accessible par Prometheus, puis restreindre le pare-feu ou le réseau de conteneurs afin que seul l'hôte Prometheus puisse se connecter au port privé. N'exposez pas les ports 8080 ou 8443 sur Internet : Jitsi décrit explicitement cette interface comme privée et indique que ses points de terminaison ne sont pas destinés à un accès public. Si l'environnement requiert un chiffrement en transit, l'interface privée prend en charge TLS lorsqu'elle est configurée avec un magasin de clés ; vous pouvez également utiliser un proxy TLS interne strictement contrôlé. Évitez de copier une liaison publique trop large sans 0.0.0.0restriction d'accès associée.

Après avoir modifié un paramètre d'écouteur, utilisez le mécanisme de configuration pris en charge par votre déploiement et redémarrez ou rechargez JVB uniquement si nécessaire. Un redémarrage peut interrompre les appels sur un déploiement à pont unique ; planifiez-le donc en conséquence. Dans Docker, modifiez la configuration persistante côté hôte ou l'environnement utilisé pour la générer, et non un fichier de conteneur temporaire. Vérifiez l'écouteur depuis la machine Prometheus curlavant de continuer.

Étape 3 : Ajouter une tâche de scraping Prometheus

Ajoutez une tâche de récupération de données au fichier de configuration Prometheus. Dans l'exemple sur le même hôte, la section concernée est :

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

La configuration Prometheus utilise scrape_configset prend en charge les cibles statiques pour un déploiement fixe de petite taille. Si le JVB se trouve dans un conteneur distinct, 127.0.0.1il doit pointer vers le conteneur Prometheus lui-même ; utilisez plutôt le nom de service et le port du JVB sur un réseau Docker privé partagé. Pour un hôte distant, utilisez son nom ou son adresse DNS privée et limitez les règles de pare-feu. La documentation de référence de la configuration Prometheus explique les tâches de scraping, les cibles et les paramètres d'intervalle.

Avant d'appliquer une modification, validez le fichier complet avec l'utilitaire Prometheus fourni avec votre installation :

promtool check config /etc/prometheus/prometheus.yml

Si la validation réussit, rechargez Prometheus en utilisant la méthode configurée pour votre service, ou redémarrez-le si les rechargements ne sont pas activés. Ne vous fiez pas uniquement à un fichier YAML valide pour conclure à la réussite de l'opération ; une cible syntaxiquement valide peut néanmoins être inaccessible.

Étape 4 : Connecter Grafana à Prometheus

Dans Grafana, ajoutez la source de données Prometheus intégrée et saisissez l'URL accessible par Grafana. Sur un hôte unique, il peut s'agir de l' http://localhost:9090URL de l'hôte si Grafana y est exécuté directement. Si Grafana est exécuté dans un conteneur, localhostil s'agit du conteneur Grafana lui-même, et non de l'hôte ou du conteneur Prometheus ; utilisez le nom du service Prometheus sur un réseau partagé. Enregistrez et testez la source de données. Le guide de Grafana relatif aux sources de données Prometheus décrit les paramètres de connexion, et sa documentation explique comment Grafana interroge un système de métriques.

Ouvrez Explorer, sélectionnez Prometheus et exécutez la commande up{job="jitsi-videobridge"}. Il s'agit d'un contrôle d'intégrité de Prometheus, et non d'une métrique Jitsi. La valeur 1 indique que Prometheus a correctement collecté les données de la cible pour l'évaluation en cours ; la valeur 0 indique qu'une cible configurée a échoué. Si la requête ne renvoie aucune série, vérifiez le nom exact de la tâche, le rechargement de la configuration, la découverte de la cible et la plage horaire sélectionnée.

Étape 5 : Créer un tableau de bord utile et vérifier les données

Une fois uple système opérationnel, utilisez l'explorateur de métriques de Grafana Explore ou l'explorateur d'expressions de Prometheus pour identifier les séries JVB exposées par votre version. Commencez par quelques questions opérationnelles :

• Combien de conférences et de points de terminaison sont actifs, et comment ces chiffres évoluent-ils au cours de la journée ?
• Les débits binaires ou les débits de paquets RTP entrants et sortants évoluent-ils à mesure que la charge des réunions augmente ?
• La contrainte du pont augmente-t-elle avec le nombre de points d'extrémité, ou est-elle déjà élevée pour une charge modérée ?
• Les métriques relatives aux threads JVM et au ramasse-miettes sont-elles disponibles, et varient-elles en fonction des rapports d'appels lents ?

Utilisez les noms et unités des métriques fournis par votre propre /metricspoint de terminaison. La documentation statistique de Jitsi décrit des exemples tels que conferences` <td> endpoints`, bit_rate_download... bit_rate_uploadet `<td>` stress_leveldans sa liste de statistiques prises en charge, mais précise que toutes les statistiques ne sont pas actuellement disponibles au format Prometheus. Ne collez pas ces noms dans une requête tant que vous n'avez pas vérifié la présence de la famille Prometheus dans votre configuration. Pour les compteurs cumulatifs, utilisez des fonctions PromQL telles que `<td>` rate()sur une plage ; pour les indicateurs instantanés, comme le nombre de participants à la conférence, représentez graphiquement la valeur échantillonnée directement. Conservez les unités documentées lors de l'étiquetage des panneaux, car les champs de débit binaire et les débits de paquets utilisent des unités différentes.

Créez un tableau de bord avec quelques panneaux de séries temporelles, des unités claires et une période incluant les extractions récentes. Évitez de considérer une série manquante comme nulle : l’absence de données peut indiquer une faute de frappe, une métrique non prise en charge ou un échec d’extraction. Pour les alertes, commencez par définir la disponibilité cible, puis ajoutez des seuils uniquement après avoir observé un trafic normal sur votre déploiement. Un seuil de « forte charge » universel peut être trompeur, car la capacité dépend de l’hôte, du type de média et de la configuration.

Vérifiez la configuration finale

Exécutez cette séquence de la plus simple à la plus spécifique :

1. Sur l'hôte JVB, demandez http://127.0.0.1:8080/metricset confirmez que la réponse contient du texte de métrique.
2. Depuis l'hôte ou le conteneur Prometheus, effectuez une requête vers le même point de terminaison en utilisant l'adresse privée configurée. Une requête locale réussie ne garantit pas l'accessibilité à distance.
3. Dans la vue Cibles de Prometheus, vérifiez que la jitsi-videobridgecible est opérationnelle et examinez sa dernière erreur de récupération si elle est hors service.
4. Dans Grafana Explore, vérifiez up{job="jitsi-videobridge"}que le résultat est 1, puis interrogez un nom de métrique JVB copié depuis le point de terminaison en direct.
5. Ouvrez un tableau de bord sur une période incluant plusieurs intervalles de collecte de données et vérifiez que les unités, les étiquettes et les horodatages sont cohérents.

Si le point de terminaison fonctionne en local mais que Prometheus signale une erreur de connexion, vérifiez l'adresse de liaison, le port, le pare-feu et la configuration réseau du conteneur. Si la cible est active mais que les requêtes JVB sont vides, vérifiez le nom exporté exact, la plage horaire sélectionnée et si cette statistique figure dans la sortie Prometheus. Si les tableaux de bord affichent des données mais que la qualité des réunions reste dégradée, les indicateurs permettent d'orienter l'investigation ; ils ne permettent pas, à eux seuls, d'identifier un problème de connexion Wi-Fi locale, de navigateur ou de réseau du dernier kilomètre d'un participant.

Cette configuration suit la documentation amont de Jitsi, Prometheus et Grafana révisée le 6 octobre 2026. Étant donné que la configuration de référence de Jitsi et les écrans de Grafana évoluent, comparez les exemples avec la documentation et les fichiers correspondant aux versions exactes que vous utilisez.