comrelay/livekit/LOAD_TEST.md

화상회의 부하 테스트 가이드 (단계 5: 확장 검증)

lk load-test(livekit-cli)로 가상 참여자를 대량 접속시켜 SFU 부하·미디어 품질을 측정한다. 러너: livekit/load-test.sh

---

1. 목적

• 다수 참여자 접속 시 품질(지연·패킷 손실·대역폭) 이 유지되는지 검증
• (셀프호스팅 클러스터) 여러 SFU 노드로 미디어 트래픽이 분산되는지 검증
• 문서 목표: 최대 160명 단일 방, 동시 표시 ~50명, Simulcast/SVC 로 수신측 화질 차등

---

2. 사전 준비

• Docker 설치 (러너가 livekit/livekit-cli 이미지를 사용)
• 자격증명: 루트 .env.${APP_ENV:-development} 의 LIVEKIT_URL / LIVEKIT_API_KEY / LIVEKIT_API_SECRET
  • 러너가 자동으로 읽어 컨테이너에 주입한다.

---

3. 실행

# 소규모(도구/연결 검증) — Cloud 에서도 안전
./livekit/load-test.sh smoke      # 2 pub + 3 sub, 15s, 저해상도

# 중간 규모
./livekit/load-test.sh medium     # 5 pub + 30 sub, 1m

# 대규모(문서 목표) — 반드시 셀프호스팅/전용 인스턴스에서!
./livekit/load-test.sh full       # 10 pub + 150 sub, 2m, 고해상도

세부 조정(환경변수):

변수	의미	예
PUBLISHERS	영상 발행 가상 참여자 수	10
SUBSCRIBERS	구독 전용 가상 참여자 수	150
DURATION	지속 시간	2m, 30s
RESOLUTION	발행 화질	low / medium / high
LAYOUT	구독 레이아웃(구독 수 모사)	speaker / 3x3 / 4x4 / 5x5
SIMULCAST	Simulcast 발행	on(기본) / off
ROOM	방 이름	loadtest-full
NUM_PER_SECOND	초당 입장 가속	5

# 예) 160명 규모, 진행자 1명 고해상도 + 159명 구독, 3분
PUBLISHERS=1 SUBSCRIBERS=159 RESOLUTION=high DURATION=3m ./livekit/load-test.sh full

---

4. 결과 읽는 법

러너는 두 표를 출력한다.

• Track loading: 구독자별 각 트랙의 수신 패킷 수, 비트레이트, 패킷 손실
• Subscriber summaries: 구독자별 Tracks N/N(구독 성공 비율), 총 비트레이트, 총 패킷 손실, 에러

합격 기준(목표치)

• Tracks 가 모두 N/N (요청 트랙 전부 구독)
• Pkt. Loss 가 낮게 유지 (목표 < 2~3%)
• Error = 0
• 참여자 수를 늘려도 위 지표가 급격히 악화되지 않을 것

smoke 예시 결과: 6/6 트랙, 패킷 손실 0%, ~119kbps/구독자 — 정상.

---

5. 어디서 실행하나 (중요)

대상	권장
LiveKit Cloud (현재 dev)	smoke 만. 대량 부하는 동시접속 쿼터·약관 위반 소지 → 금지
셀프호스팅 단일 노드 (단계 6)	medium~full 로 단일 노드 한계 측정
셀프호스팅 클러스터 (단계 6)	full 이상으로 부하 분산(노드 간 트래픽 분배) 검증

• 부하 분산 검증은 SFU 노드가 2개 이상인 클러스터 구성에서만 의미가 있다(단일 노드는 분산 대상이 없음).

---

6. 서버 측 모니터링 (셀프호스팅)

부하 중 서버 지표를 함께 본다.

• LiveKit Prometheus 메트릭(/metrics) + Grafana: 노드별 참여자/트랙 수, CPU, 송수신 대역폭
• 호스트: CPU, 네트워크 대역폭, UDP 버퍼
• 노드별 참여자 분포(클러스터링/캐스케이딩이 고르게 분산하는지)

---

7. 한계 / 참고

• lk load-test 의 발행 미디어는 합성 트래픽이라 실제 카메라 화질과 100% 동일하지는 않다(상대적 부하 비교용으로 충분).
• 클라이언트 측 다운링크(시청자 회선) 부하는 별도 검증 필요.
• 본 단계는 검증 도구·방법론이며, 실제 대규모 검증은 단계 6(셀프호스팅 배포) 환경에서 수행한다.