Prometheus와 Grafana를 사용하여 Jitsi Videobridge 메트릭을 모니터링하는 방법

Jitsi 회의가 끊기기 시작하면 관리자는 오디오 끊김이나 비디오 멈춤 현상에 대한 불만을 접할 수 있지만, 브리지가 과부하 상태인지, 연결할 수 없는 상태인지, 아니면 단순히 평소보다 트래픽이 많은 것인지 신속하게 파악할 방법이 없습니다. Jitsi Videobridge(JVB)는 Prometheus가 수집하고 Grafana에서 표시할 수 있는 운영 지표를 제공합니다. 이 가이드에서는 로컬 엔드포인트 점검부터 시작하여 검증 가능한 대시보드를 구축하는 실질적인 설정 과정을 안내합니다.

예시 시나리오: 소규모 조직에서 Linux 호스트에 JVB 하나를 설치하고, 같은 호스트에서 Prometheus와 Grafana를 실행하는 상황을 가정해 보겠습니다. 이는 설명 목적으로 제시된 예시이며, 실제 배포 또는 테스트 보고서가 아닙니다. 서비스가 별도의 컨테이너 또는 다른 서버에서 실행되는 경우, 접근 가능한 내부 주소를 사용하고 동일한 네트워크 제한을 유지하십시오.

당신이 모니터링할 내용은 무엇입니까?

현재 JVB 프로젝트 문서에는 브리지의 개인 HTTP 인터페이스에 내장된 Prometheus/OpenMetrics 엔드포인트에 대한 설명이 있습니다 /metrics. 이 엔드포인트는 활성 회의, 엔드포인트, 수신 및 송신 비트 전송률, 패킷 전송률, 브리지 부하 등의 통계를 표시합니다. Prometheus 엔드포인트는 JVB의 다른 보고 형식에서 제공되는 모든 통계를 포함하지 않을 수 있으므로, 설치된 릴리스에서 제공하는 엔드포인트를 기준으로 삼아야 합니다. 현재 참조 구성은 Prometheus REST 리소스를 활성화하고 개인 HTTP 인터페이스를 루프백에 바인딩합니다. 문서에 명시된 기본 개인 HTTP 포트는 8080입니다. 이전 패키지 및 배포 템플릿은 다를 수 있습니다.

Prometheus는 시계열 데이터를 수집하여 저장합니다. Grafana는 Prometheus를 데이터 소스로 사용하여 저장된 시계열 데이터를 쿼리합니다. 이 직접적인 JVB 메트릭 경로에는 별도의 Jitsi 익스포터가 필요하지 않습니다. Jitsi의 통계 및 Prometheus 엔드포인트 문서 , 개인 HTTP 인터페이스 구성 , 그리고 참조 구성을 참조하십시오 . 이러한 업스트림 파일은 변경될 수 있으므로 예제 값을 적용하기 전에 브리지에 설치된 구성 및 버전을 확인하십시오.

1단계: JVB가 메트릭을 제공하는지 확인합니다.

JVB 머신에서 먼저 활성 구성을 확인하십시오. 일반적인 Debian 또는 Ubuntu 패키지는 를 사용 /etc/jitsi/videobridge/jvb.conf하지만, Jitsi는 실제 파일은 브리지 프로세스에 전달된 경로라고 명시합니다. 컨테이너 배포 환경에서는 생성된 구성 파일이 마운트될 수도 있습니다. 샘플 파일이 실행 중인 서비스가 읽는 파일이라고 가정하지 마십시오.

예제의 기본 포트와 루프백 바인딩을 사용하여 JVB 호스트에서 다음 명령을 실행하십시오.

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

성공적인 응답은 프로메테우스 메트릭 패밀리를 포함하는 일반 텍스트이며, 종종 샘플이 포함된 줄이 함께 표시됩니다 # HELP. # TYPE그림은 명령만 보여주는 것이며, 실제 서버 응답을 나타내는 것은 아닙니다. 연결 거부는 일반적으로 JVB가 중지되었거나, 다른 주소 또는 포트에서 수신 대기 중이거나, 설치된 구성에서 해당 HTTP 리스너가 비활성화되었음을 의미합니다. HTTP 404 오류는 서버가 응답했지만 해당 빌드 또는 API 구성에서 경로를 사용할 수 없음을 나타냅니다. 프로메테우스 경로가 작동하도록 하기 위해 관련 없는 Colibri 제어 API를 활성화하기보다는 JVB 로그와 설치된 릴리스의 구성을 확인하십시오.

다음 명령어를 사용하여 메트릭 이름과 유형을 직접 확인할 수 있습니다.

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

JVB 문서에는 사용 가능한 Prometheus 메트릭이 JSON 통계와 완전히 일치하지 않는다는 내용이 명시되어 있습니다. 또한 Prometheus 형식으로만 제공되는 컨퍼런스 규모 히스토그램에 대한 내용도 포함되어 있습니다. PromQL 쿼리를 작성하거나 특정 이름을 사용하는 대시보드를 가져오기 전에 설치된 버전이 실제로 무엇을 반환하는지 확인하십시오.

2단계: 개인 인터페이스를 비공개로 유지하세요

Prometheus가 JVB와 동일한 호스트에서 실행되는 경우, 개인 인터페이스를 활성화 상태로 유지하십시오 127.0.0.1. 이렇게 하면 네트워크에 대한 추가 리스너를 열지 않아도 됩니다. 가상의 동일 호스트 설정에서 127.0.0.1:8080Prometheus는 대상에 직접 접근할 수 있습니다.

Prometheus가 다른 곳에서 실행되는 경우, JVB의 기본 루프백 바인딩은 Prometheus로부터의 연결을 허용하지 않습니다. Prometheus에서 접근 가능한 내부 인터페이스에 바인딩되도록 프라이빗 리스너를 구성한 다음, 방화벽 또는 컨테이너 네트워크를 제한하여 Prometheus 호스트만 프라이빗 포트에 연결할 수 있도록 해야 합니다. 포트 8080 또는 8443을 공용 인터넷에 노출하지 마십시오. Jitsi는 이 인터페이스를 명시적으로 프라이빗 인터페이스로 설명하고 있으며, 해당 엔드포인트는 공용 액세스를 위한 것이 아니라고 명시하고 있습니다. 전송 중 암호화가 필요한 환경에서는 키 저장소를 구성하여 프라이빗 인터페이스가 TLS를 지원하도록 설정할 수 있습니다. 또는 엄격하게 제어되는 내부 TLS 프록시를 사용하십시오. 0.0.0.0접근 제한 없이 광범위한 공용 바인딩을 복사하여 사용하는 것은 피하십시오.

리스너 설정을 변경한 후에는 배포 환경에서 지원하는 구성 메커니즘을 사용하고, 해당 릴리스에서 요구하는 경우에만 JVB를 재시작하거나 다시 로드하십시오. 재시작은 단일 브리지 배포 환경에서 호출을 중단시킬 수 있으므로 적절하게 일정을 조정해야 합니다. Docker 환경에서는 임시 컨테이너 파일이 아닌, 해당 파일을 생성하는 데 사용된 영구 호스트 측 구성 또는 환경 변수를 편집하십시오. curl계속 진행하기 전에 Prometheus 머신에서 리스너를 확인하십시오.

3단계: Prometheus 스크래핑 작업을 추가합니다.

Prometheus 설정 파일에 스크래핑 작업을 추가합니다. 동일 호스트 예시의 경우 관련 섹션은 다음과 같습니다.

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

Prometheus 구성은 scrape_configs소규모 고정 배포를 위해 정적 대상을 사용하고 지원합니다. JVB가 다른 컨테이너에 있는 경우 127.0.0.1Prometheus 컨테이너 자체를 가리키도록 설정하고, 공유된 프라이빗 Docker 네트워크에서 JVB 서비스 이름과 포트를 사용하십시오. 원격 호스트의 경우 해당 호스트의 프라이빗 DNS 이름 또는 주소를 사용하고 방화벽 규칙을 제한적으로 설정하십시오. Prometheus 구성 참조에서 스크래핑 작업, 대상 및 간격 설정에 대해 자세히 설명합니다.

변경 사항을 적용하기 전에 설치에 포함된 Prometheus 유틸리티를 사용하여 전체 파일의 유효성을 검사하십시오.

promtool check config /etc/prometheus/prometheus.yml

유효성 검사가 성공하면 서비스에 구성된 방법을 사용하여 Prometheus를 다시 로드하거나, 다시 로드가 활성화되어 있지 않으면 서비스를 재시작하십시오. 유효한 YAML 파일만으로 성공을 단정짓지 마십시오. 구문적으로 유효한 대상이라도 도달할 수 없는 경우가 있을 수 있습니다.

4단계: Grafana를 Prometheus에 연결합니다.

Grafana에서 내장 Prometheus 데이터 소스를 추가하고 Grafana 자체 http://localhost:9090에서 접근할 수 있는 URL을 입력합니다. Grafana가 호스트에서 직접 실행되는 경우 해당 호스트의 URL을 입력하면 됩니다. Grafana가 컨테이너에서 실행되는 경우, localhost호스트나 Prometheus 컨테이너가 아닌 Grafana 컨테이너의 URL을 입력해야 합니다. 공유 네트워크 환경에서는 Prometheus 서비스 이름을 사용합니다. 데이터 소스를 저장하고 테스트합니다. Grafana의 Prometheus 데이터 소스 가이드에서 연결 설정에 대한 설명을 확인할 수 있으며, 데이터 소스 설명서에서는 Grafana가 메트릭 백엔드를 쿼리하는 방법을 설명합니다.

탐색기를 열고 Prometheus를 선택한 다음 실행하세요 up{job="jitsi-videobridge"}. 이는 Jitsi 메트릭이 아닌 Prometheus 스크랩 상태 확인입니다. 값이 1이면 Prometheus가 현재 평가 대상에 대한 스크랩을 성공적으로 수행했음을 의미하고, 0이면 구성된 대상이 실패했음을 의미합니다. 쿼리 결과가 전혀 반환되지 않으면 정확한 작업 이름, 구성 재로드, 대상 검색 및 선택한 시간 범위를 확인하세요.

5단계: 유용한 대시보드를 구축하고 데이터를 검증합니다.

시스템이 정상 상태 이면 upGrafana Explore의 메트릭 브라우저 또는 Prometheus의 표현식 브라우저를 사용하여 릴리스에서 노출된 JVB 시리즈를 찾으십시오. 몇 가지 운영 관련 질문부터 시작해 보세요.

• 현재 활성화된 컨퍼런스와 엔드포인트는 몇 개이며, 그 수는 하루 동안 어떻게 변합니까?
• 회의 부하가 증가함에 따라 수신 및 발신 RTP 비트 전송률 또는 패킷 전송률 시리즈가 변화하고 있습니까?
• 교량 응력 계열은 종점 개수에 따라 증가하는가, 아니면 적당한 하중에서도 이미 높은가?
• JVM 스레드 및 가비지 컬렉션 관련 메트릭을 사용할 수 있습니까? 그리고 이러한 메트릭은 느린 호출 보고서 발생 시에 변경됩니까?

자체 /metrics엔드포인트에서 출력하는 메트릭 이름과 단위를 사용하십시오. Jitsi의 통계 참조 문서 에는 지원되는 통계 목록에 conferences, endpoints, bit_rate_download, bit_rate_upload와 같은 예시가 나와 stress_level있지만, 모든 통계가 현재 Prometheus 형식으로 제공되는 것은 아니라는 점에 유의해야 합니다. 빌드에 Prometheus 제품군이 포함되어 있는지 확인하기 전까지는 이러한 이름을 쿼리에 붙여넣지 마십시오. 누적 카운터의 경우, rate()범위에 대한 와 같은 PromQL 함수를 사용하고, 현재 회의 수와 같은 순간적인 게이지의 경우 샘플링된 값을 직접 그래프로 표시하십시오. 비트 전송률 필드와 패킷 전송률은 서로 다른 단위를 사용하므로 패널 레이블을 지정할 때 문서화된 단위를 유지하십시오.

시계열 패널 몇 개, 명확한 단위, 그리고 최근 스크래핑 데이터를 포함하는 시간 범위를 가진 대시보드를 생성하세요. 누락된 시계열을 0으로 처리하지 마세요. 데이터가 없는 것은 철자 오류, 지원되지 않는 메트릭 또는 스크래핑 실패를 나타낼 수 있습니다. 알림 설정 시에는 목표 가용성부터 시작하여 실제 배포 환경에서 정상적인 트래픽을 관찰한 후에 임계값을 추가하세요. 용량은 호스트, 미디어 구성 및 설정에 따라 달라지므로 일률적인 "높은 부하" 수치는 오해를 불러일으킬 수 있습니다.

설치가 완료되었는지 확인하세요

가장 쉬운 것부터 가장 구체적인 순서로 다음 단계를 실행하세요.

1. JVB 호스트에서 요청을 보내고 http://127.0.0.1:8080/metrics응답에 메트릭 텍스트가 포함되어 있는지 확인합니다.
2. Prometheus 호스트 또는 컨테이너에서 구성된 개인 IP 주소를 사용하여 동일한 엔드포인트에 요청하십시오. 로컬에서 성공했다고 해서 원격 연결 가능성이 보장되는 것은 아닙니다.
3. Prometheus의 대상 보기에서 jitsi-videobridge대상이 실행 중인지 확인하고, 실행 중이 아니면 마지막 스크랩 오류를 검사하십시오.
4. Grafana Explore에서 확인 up{job="jitsi-videobridge"}결과가 1인지 확인한 다음, 실제 엔드포인트에서 복사한 JVB 메트릭 이름 하나를 쿼리합니다.
5. 여러 데이터 수집 간격을 포함하는 시간 범위의 대시보드를 열고 단위, 레이블 및 타임스탬프가 올바른지 확인합니다.

엔드포인트가 로컬에서는 정상적으로 작동하지만 Prometheus에서 연결 오류가 보고되는 경우, 바인딩 주소, 포트, 방화벽 및 컨테이너 네트워킹 설정을 다시 확인하십시오. 대상이 작동 중이지만 JVB 쿼리 결과가 비어 있는 경우, 정확한 내보낸 이름, 선택한 시간 범위, 그리고 해당 통계가 Prometheus 출력에 포함되어 있는지 확인하십시오. 대시보드에 데이터가 표시되지만 회의 품질이 여전히 저하되는 경우, 지표를 통해 문제 해결 범위를 좁힐 수 있습니다. 하지만 지표 자체만으로는 참가자의 로컬 Wi-Fi, 브라우저 또는 최종 사용자 네트워크 문제를 파악할 수 없습니다.

이 구성은 2026년 10월 6일에 검토된 Jitsi, Prometheus 및 Grafana 공식 문서를 따릅니다. Jitsi의 참조 구성과 Grafana 화면은 변경될 수 있으므로, 사용 중인 정확한 버전의 문서 및 파일과 예제를 비교하십시오.