Cómo monitorizar las métricas de Jitsi Videobridge con Prometheus y Grafana

Cuando una reunión de Jitsi comienza a presentar problemas, un administrador puede ver quejas sobre audio entrecortado o video congelado, pero no tiene una forma rápida de saber si el puente está sobrecargado, inaccesible o simplemente manejando más tráfico de lo habitual. Jitsi Videobridge (JVB) expone métricas operativas que Prometheus puede recopilar y Grafana puede mostrar. Esta guía describe una configuración práctica, comenzando con una verificación del punto final local y terminando con un panel de control que puede verificar.

Escenario de ejemplo: Imagine una pequeña organización ejecutando JVB en un servidor Linux, junto con Prometheus y Grafana en el mismo servidor. Este es un ejemplo ilustrativo, no un informe de una implementación o prueba real. Si sus servicios se ejecutan en contenedores separados o en servidores diferentes, sustituya sus direcciones IP internas accesibles y mantenga las mismas restricciones de red.

Lo que usted supervisará

La documentación actual del proyecto JVB describe un punto final Prometheus/OpenMetrics integrado en /metricsla interfaz HTTP privada del puente. En él se muestran estadísticas como conferencias activas, puntos finales, tasa de bits entrante y saliente, tasas de paquetes y estrés del puente. La información de Prometheus no necesariamente incluye todas las estadísticas disponibles a través de otros formatos de informes de JVB, por lo que se recomienda utilizar el punto final de la versión instalada como fuente de información principal. La configuración de referencia habilita actualmente el recurso REST de Prometheus y vincula la interfaz HTTP privada a la interfaz de bucle invertido; el puerto HTTP privado predeterminado documentado es el 8080. Es posible que los paquetes y plantillas de implementación más antiguos presenten configuraciones diferentes.

Prometheus recopila y almacena las series temporales. Grafana se conecta a Prometheus como fuente de datos y consulta dichas series almacenadas. No se requiere un exportador Jitsi independiente para esta ruta directa de métricas JVB. Consulte la documentación de Jitsi sobre estadísticas y el punto final de Prometheus , su configuración de interfaz HTTP privada y la configuración de referencia . Estos archivos de origen pueden cambiar; verifique la configuración y la versión instalada en su propio puente antes de aplicar los valores de ejemplo.

Paso 1: Confirmar que JVB proporciona métricas

En la máquina JVB, primero identifique la configuración activa. Un paquete común de Debian o Ubuntu usa /etc/jitsi/videobridge/jvb.conf, pero Jitsi indica que el archivo real es la ruta que se le pasa al proceso de puente. Las implementaciones de contenedores pueden montar una configuración generada en su lugar. No asuma que un archivo de ejemplo es el que lee el servicio en ejecución.

Con el puerto predeterminado y la vinculación de bucle invertido del ejemplo, ejecute este comando en el host JVB:

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

Una respuesta exitosa es un texto plano que contiene familias de métricas de Prometheus, a menudo con # HELPlíneas # TYPEseguidas de ejemplos. La ilustración muestra solo el comando; no es evidencia de una respuesta del servidor en tiempo real. Un rechazo de conexión generalmente significa que JVB está detenido, escuchando en otra dirección o puerto, o que la configuración instalada desactiva ese oyente HTTP. Un HTTP 404 sugiere que el servidor respondió, pero la ruta no está disponible en esa compilación o configuración de API. Revise los registros de JVB y la configuración de su versión instalada en lugar de habilitar la API de control Colibri, que no tiene relación, solo para que funcione la ruta de Prometheus.

Puedes inspeccionar los nombres y tipos de métricas directamente con:

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

JVB documenta que las métricas disponibles de Prometheus no reflejan completamente sus estadísticas JSON. También documenta los histogramas de tamaño de conferencia, disponibles únicamente en formato Prometheus. Verifique qué devuelve realmente su versión instalada antes de escribir consultas PromQL o importar un panel que asuma nombres específicos.

Paso 2: Mantenga la interfaz privada privada

Cuando Prometheus se ejecuta en el mismo host que JVB, deje la interfaz privada abierta 127.0.0.1. Esto evita que se abra otro oyente en su red. En la configuración hipotética del mismo host, 127.0.0.1:8080Prometheus puede acceder directamente al destino.

Si Prometheus se ejecuta en otro lugar, el enlace de bucle invertido predeterminado de JVB no aceptará conexiones desde allí. Puede configurar el oyente privado para que se enlace a una interfaz interna accesible por Prometheus y, a continuación, restringir el firewall o la red del contenedor para que solo el host de Prometheus pueda conectarse al puerto privado. No exponga los puertos 8080 o 8443 a internet: Jitsi describe explícitamente esta interfaz como privada e indica que sus puntos finales no están destinados al acceso público. Si el entorno requiere cifrado en tránsito, la interfaz privada admite TLS cuando se configura con un almacén de claves; alternativamente, utilice un proxy TLS interno con un control estricto. Evite copiar un enlace público amplio sin 0.0.0.0una restricción de acceso correspondiente.

Tras modificar la configuración del oyente, utilice el mecanismo de configuración compatible con su implementación y reinicie o recargue JVB solo cuando lo requiera esa versión. Un reinicio puede interrumpir las llamadas en una implementación de puente único, así que planifíquelo adecuadamente. En Docker, edite la configuración persistente del host o el entorno utilizado para generarla, no un archivo de contenedor transitorio. Verifique el oyente desde la máquina Prometheus curlantes de continuar.

Paso 3: Añadir una tarea de extracción de datos de Prometheus

Agregue una tarea de raspado al archivo de configuración de Prometheus. Para el ejemplo del mismo host, la sección relevante es:

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

La configuración de Prometheus utiliza scrape_configsy admite destinos estáticos para una implementación fija y de tamaño reducido. Si el JVB se encuentra en un contenedor diferente, 127.0.0.1apunta al propio contenedor de Prometheus; en su lugar, utilice el nombre y el puerto del servicio JVB en una red Docker privada compartida. Para un host remoto, utilice su nombre o dirección DNS privada y mantenga la regla del firewall restrictiva. La documentación de referencia de la configuración de Prometheus explica las tareas de recopilación de datos, los destinos y la configuración de intervalos.

Antes de aplicar cualquier cambio, valide el archivo completo con la utilidad Prometheus que viene incluida con su instalación:

promtool check config /etc/prometheus/prometheus.yml

Si la validación es exitosa, recargue Prometheus usando el método configurado para su servicio, o reinícielo si las recargas no están habilitadas. No deduzca el éxito solo con un archivo YAML válido; un destino sintácticamente válido aún puede ser inaccesible.

Paso 4: Conectar Grafana con Prometheus

En Grafana, agregue la fuente de datos Prometheus integrada e ingrese la URL a la que Grafana puede acceder. En un host, esto podría ser http://localhost:9090si Grafana se ejecuta directamente en ese host. Cuando Grafana se ejecuta en un contenedor, localhostse refiere al contenedor de Grafana, no al host ni al contenedor de Prometheus; use el nombre del servicio Prometheus en una red compartida. Guarde y pruebe la fuente de datos. La guía de la fuente de datos Prometheus de Grafana describe la configuración de conexión, y su documentación explica cómo Grafana consulta un backend de métricas.

Abra Explore, seleccione Prometheus y ejecute up{job="jitsi-videobridge"}. Esta es una comprobación de estado de recopilación de datos de Prometheus, no una métrica de Jitsi. Un valor de 1 significa que Prometheus recopiló correctamente los datos del objetivo para la evaluación actual; 0 significa que un objetivo configurado está fallando. Si la consulta no devuelve ninguna serie, confirme el nombre exacto del trabajo, la recarga de la configuración, la detección del objetivo y el rango de tiempo seleccionado.

Paso 5: Crea un panel de control útil y verifica los datos.

Una vez upque esté en buen estado, utilice el explorador de métricas de Grafana Explore o el explorador de expresiones de Prometheus para encontrar la serie JVB expuesta por su versión. Comience con un pequeño conjunto de preguntas operativas:

• ¿Cuántas conferencias y puntos finales están activos, y cómo varían esas cifras a lo largo del día?
• ¿Cambian las series de tasas de bits o de paquetes RTP entrantes y salientes a medida que aumenta la carga de la reunión?
• ¿La serie de tensiones del puente aumenta a medida que aumenta el número de puntos finales, o ya es alta con una carga moderada?
• ¿Están disponibles las métricas de subprocesos y recolección de basura de la JVM, y cambian en torno a los informes de llamadas lentas?

Utilice los nombres y unidades de las métricas que imprime su propio /metricsendpoint. La referencia de estadísticas de Jitsi describe ejemplos como conferences, endpoints, bit_rate_download, bit_rate_upload, y stress_levelen su lista de estadísticas compatibles, pero advierte que no todas las estadísticas se exponen actualmente en formato Prometheus. No pegue esos nombres en una consulta hasta que confirme que la familia Prometheus existe en su compilación. Para contadores acumulativos, utilice funciones PromQL como rate()sobre un rango; para medidores instantáneos como el recuento de conferencias actual, grafique el valor muestreado directamente. Conserve las unidades documentadas al etiquetar los paneles, ya que los campos de tasa de bits y las tasas de paquetes utilizan unidades diferentes.

Crea un panel con algunos paneles de series temporales, unidades claras y un rango de tiempo que incluya las últimas recopilaciones de datos. Evita considerar una serie faltante como cero: la ausencia de datos puede indicar un error ortográfico, una métrica no compatible o un fallo en la recopilación de datos. Para las alertas, comienza con la disponibilidad del objetivo y luego agrega umbrales solo después de haber observado un tráfico normal en tu propia implementación. Un valor universal de "alta carga" puede ser engañoso, ya que la capacidad depende del host, la combinación de medios y la configuración.

Compruebe la configuración finalizada.

Ejecute esta secuencia de la más sencilla a la más específica:

1. En el host JVB, solicite http://127.0.0.1:8080/metricsy confirme que la respuesta contiene el texto de la métrica.
2. Desde el host o contenedor de Prometheus, solicite el mismo punto final utilizando la dirección privada configurada. Un éxito local no demuestra la accesibilidad remota.
3. En la vista Objetivos de Prometheus, confirme que el jitsi-videobridgeobjetivo está activo e inspeccione el último error de rastreo si está inactivo.
4. En Grafana Explore, confirme up{job="jitsi-videobridge"}que devuelve 1 y, a continuación, consulte un nombre de métrica JVB copiado del punto final en vivo.
5. Abra un panel de control que abarque un rango de tiempo que incluya varios intervalos de recopilación de datos y compruebe que las unidades, las etiquetas y las marcas de tiempo tengan sentido.

Si el punto final funciona localmente pero Prometheus informa un error de conexión, revise la dirección de enlace, el puerto, el firewall y la configuración de red del contenedor. Si el destino está activo pero las consultas JVB están vacías, verifique el nombre exportado exacto, el rango de tiempo seleccionado y si esa estadística está presente en la salida de Prometheus. Si los paneles muestran datos pero la calidad de la reunión sigue siendo deficiente, las métricas ayudan a acotar la investigación; por sí solas no identifican el problema de la conexión Wi-Fi local, el navegador o la red de última milla de un participante.

Esta configuración sigue la documentación oficial de Jitsi, Prometheus y Grafana, revisada el 6 de octubre de 2026. Dado que la configuración de referencia de Jitsi y las pantallas de Grafana evolucionan, compare los ejemplos con la documentación y los archivos correspondientes a las versiones exactas que utiliza.