증상별 트러블슈팅 매트릭스

마지막 업데이트 2026-07-22

장애 신고가 들어왔을 때 증상 → 즉시 확인 신호 → 의심 원인 → 코드/문서로 곧장 진입하기 위한 트리아지 색인. 심층 분석은 각 행이 가리키는 bugs/ 문서에, 코드 동작 전체 흐름은 architecture/·features/ 문서에 있다. 이 문서는 그 사이를 잇는 한 겹의 색인이다.

DRAFT 트리아지 색인 #소리안들림 #영상끊김 #자동전환 #누적시간 #DECODE_OVERLOAD
쓰는 법 — 3단계. ① 신고 표현과 가장 가까운 증상을 아래 빠른 색인에서 고른다 → ② 해당 군 표의 즉시 확인 신호로 현장 로그(LogRocket·Grafana Loki ppi-socket)를 먼저 본다 → ③ 의심 원인이 맞으면 코드 위치로, 정황이 불확실하면 분석 문서로 들어간다. 표에 없는 새 신고이거나 재현이 필요하면 /repro-path 스킬로 roomId 교차조사를 돌린다.
경계. 이 매트릭스의 의심 원인은 과거 분석에서 확정·유력으로 결론난 가설이다. 같은 증상이라도 원인은 매번 다를 수 있으니, 코드로 바로 가기 전에 항상 즉시 확인 신호로 한 번 검증한다. ☠️ 표시는 코드 결함이 아닌 외부/기기 요인으로 결론난 케이스.

빠른 색인

🔇 소리·마이크 무음 📢 AI 발화 음질·노이즈 🎞️ 영상·오디오 끊김 / DECODE_OVERLOAD ⏭️ 영상 자동전환 실패 ⏱️ 누적·경과시간 회귀 📝 녹음·캡션(STT) 누락·어긋남 🛠️ 녹음 후처리 부하(서버) 🧑‍🎤 아바타 매칭·립싱크 🌐 네트워크 품질·단절 🔔 알림 프리셋 동기화 🔌 AI 세션 시작 실패

🔇 소리·마이크 무음

증상(신고 표현)즉시 확인의심 원인코드 위치분석 문서
아동 영상·말풍선은 정상, 소리만 안 들림 Loki ppi-socket: relay 트랙 enabled 여부 · 노이즈 게이트(−55dBFS) 상태 (A) 마이크 입력이 게이트 아래로 떨어져 무음, 또는 (B) 호스트 isLessonStarted 게이트 미충족 use-audio-processing-chain.ts:19-24, 114-133 · monitor-dashboard/[group]/[roomId]/page.tsx:220, 723-731 아동070 1회기
수업 중 갑자기 진행자측 게스트 마이크+AI 무음 Loki: MFCC stale 이벤트 폭주(35→66) · Consumer not found 에러 mic producer churn(240ms close/recreate) → 호스트 consume race, 실패 시 retry 없이 warn만 use-mediasoup-producer.ts:463-536 · use-mediasoup-consumer.ts:322-341 · use-guest-page-session.ts:904 모니터 게스트 마이크 무음
트랙·producer는 정상인데 오디오 샘플 0(저사양 안드로이드) External STT DUPLICATE CHUNK SKIPPED 연속 · Realtime speech/transcription 0건 저사양 기기(2GB) 오디오 HAL이 동시 부하(STT+AI+mediasoup)로 캡처 소스 무음 송출 use-guest-audio-capture.ts (HAL 계층 — 무음 감시 계측 권장) 아동274 마이크 무음
setSinkId 후 시스템 볼륨 슬라이더가 안 먹힘 (설계 한계 — 로그 신호 아님) ☠️ 설계 setSinkId()가 OS 오디오 세션(Core Audio/WASAPI)을 우회 → 시스템 볼륨 레이어 밖 use-ai-session.ts · meet-video.tsx · use-host-session-relay.ts setSinkId 시스템볼륨 우회
사운드 이슈 묶음(끊김/무음/오인식/간헐) 분류 케이스별 LogRocket 원인 다양 — MFCC 미갱신·기기 설정(헤드셋→USB)·종료 API 버그 등 케이스별 (통일 위치 없음) 사운드 이슈 종합 분석

관련 코드흐름 → 세션 릴레이 · SFU 서버 · mediasoup 클라이언트 · 볼륨 증폭기 · 오디오 처리 체인

📢 AI 발화 음질·노이즈

증상(신고 표현)즉시 확인의심 원인코드 위치분석 문서
AI 발화가 지지직/찌그러짐 WAV peak 0dBFS · 클리핑 샘플(1.8%) · RMS 과대(−3~−5dBFS) aiAudioStream float 신호 ±1.0 초과 → toInt16 하드 클램프 use-guest-page-session.ts:847-854 · use-ai-session.ts:1683, 1706 AI발화 지지직 클리핑
간헐적 큰 정적/크래클 노이즈 배포 타임라인 대조 · getStats RTP 통계 · 타팀 독립 보고 여부 ☠️ 외부 OpenAI gpt-realtime 서버측 회귀 1순위(우리 코드 배제됨) (코드 무관) gpt-realtime 정적노이즈
AI 발화 중 기계음 오탐 → 세션 중단 getStats concealedSamples/concealmentEvents · jitter ≥80ms · packetsLost PLC(패킷손실 복구) 반복 프레임이 기계음 기준(CV≈0) 통과 → 오탐 use-ai-audio-noise-guard.ts:456-467 (isEffectiveNoiseFrame = isNoiseFrame && !isPlcActive) PLC 기계음 오탐지

관련 코드흐름 → AI 오디오 노이즈 가드 · MFCC 튜닝 변천사 · 기계음 영어발화 감지

🎞️ 영상·오디오 끊김 / DECODE_OVERLOAD

증상(신고 표현)즉시 확인의심 원인코드 위치분석 문서
노트북/데스크탑에서 720p 재생 끊김 isLowPerformanceDevice()=false(UA 기반) · droppedFrames 급증 저사양 분류가 Android/iOS만 → 노트북/데스크탑이 고사양으로 취급되어 720p 수신 lib/utils.ts (initLowPerformanceDevice, _checkDesktopDecodingCapability) · PR #651 노트북·데스크탑 DECODE_OVERLOAD
6코어/8GB 기기에서 영상 중 반복 끊김·자동전환 실패 droppedFrames ~31% · bufferedAheadSec 충분(33.5s)인데 발생 lowPerf 기준(≤2코어 or ≤4GB) 통과 후 720p 1800kbps 수신 → 동시 부하로 과부하 lib/utils.ts (lowPerf 판정) + Lambda 인코딩 함수 DECODE_OVERLOAD lowPerf 개선
240Hz 고주사율 노트북에서 재생 속도 저하·끊김 벽시계 > 영상진행(67%) · droppedFrames 가속 · ffmpeg 297배속(디코드는 무부하) 디코드가 아니라 디코드→표시(present) 파이프라인 stall(4.2ms 프레임 예산 초과) meet-video.tsx:554 (catch-all DECODE_OVERLOAD 오분류) MSI 240Hz present stall
고사양 기기인데 아동측 화면·오디오 동시 끊김 bufferedAhead 33.5 · dropped 1%(정상) · 고사양 판정인데 DECODE_OVERLOAD 라벨 오분류(catch-all). 카메라 3레이어 simulcast 등 동시 미디어 부하로 present 여유 부족 meet-video.tsx:548-557 · use-mediasoup-producer.ts:412 · constants.ts:97-112 아동측 동시 인코딩 부하
simulcast 인코딩이 끊김/업링크 stall 원인인지 검증 [SIMULCAST-LOAD]: cpuLimited · totalEncodeMsPerFrame · powerEfficientEncoder · activeLayers 3레이어 인코딩이 CPU/HW 코덱 점유 → 디코드 starvation + 업링크 대역폭 점유 use-mediasoup-producer.ts (인코딩 config·레이어별 stats 로깅) S10FE simulcast 검증
카메라 고화질 레이어가 낭비 인코딩 모니터가 썸네일(최저 레이어)만 소비 · set-consumer-layers emit 캡처 제약 없음(기기 기본 1080p) + 3화질 동시 인코딩으로 상시 NVENC/CPU 점유 use-guest-media-manager.ts:335 · use-mediasoup-producer.ts:415 · use-mediasoup-consumer.ts:299, 718 카메라 인코딩 경량화
수업 중 갑자기 연결 두절(removeChild 에러 동반) [NETWORK_QUALITY] external/server 모두 null(issue=user-network) · Grafana 서버 메트릭 정상 ☠️ 외부 아동 단말 로컬 인터넷(Wi-Fi/ISP) 전면 단절. removeChild는 해체 중 React DOM race 부수증상 use-network-quality.ts:124 (user-network 판정) · engine.io keepalive 아동004 29회기 네트워크 단절

관련 코드흐름 → mediasoup 클라이언트(simulcast) · WebRTC 모니터링 getStats · 저사양 기기 분류 기준 · 240Hz 주사율 가이드

⏭️ 영상 자동전환 실패

증상(신고 표현)즉시 확인의심 원인코드 위치분석 문서
full:video 완료 후 자동전환 미발생, 호스트 수동 전환 DECODE_OVERLOAD 반복(8회) · Video ended event fired 미발생(3경로 전부) currentTime 지연 + isPlayingRef.current===false 가드가 타이머 만료 시 조기 종료 meet-video.tsx:342-373 영상종료 자동전환 미발생 watchdog 분석
영상 완료 시 자동전환 실패(2건) Grafana Guest video play started 9 · guest-video-end 0 · Host changed step 2 아동 클라이언트의 종료 감지/onEnd 경로 미실행 → 서버 도달 전 실패 meet-video.tsx:232-240 · guest-layout-content.tsx:113-118 · session-handlers.ts:207-247 아동247 24회기 재현경로
전환은 발동했으나 게스트 통지가 26초 지연 클라 emit → 서버 수신 26초 공백 · 게스트→서버 업링크만 stall socket.io 업링크 stall, engine.io ping 타임아웃 범위 내라 disconnect 미발생 socket-uplink-stall-detector.ts(신규) · guest-step-utils.ts · use-guest-socket.ts 게스트 소켓 업링크 stall
NAVER 인앱 웹뷰에서 종료 이벤트 미발생 DECODE_OVERLOAD 반복 · 종료 fallback 3경로 전부 실패 웹뷰 제한된 HW 디코딩 + 저사양 동시 부하, 웹뷰가 Chrome으로 오판되어 경고 미발생 user-agent-utils.ts:detectInAppBrowser() · use-in-app-browser-redirect.ts(신규) NAVER 인앱 종료 이벤트
녹음 mp3가 activity-3 이후 누락(20분 중 7:55까지만) 음성 전환 시간 2→3 20.9초 · ffmpeg transitioned 로그 인트로 영상 19초 지연 → stale producer 참조 + consumer.resume() 무음 swallow recordingManager.ts:1001-1014(stale producer) · recordingManager.ts:1071-1076(resume 무음) mediasoup 녹음 전환 끊김

관련 코드흐름 → Activity 시스템(step·jumpConfig·autoFinish)

⏱️ 누적·경과시간 회귀

증상(신고 표현)즉시 확인의심 원인코드 위치분석 문서
게스트 재접속 직후 경과시간 ~80초 감소(03:49→02:29) LogRocket Sessions loaded: {count: 0} (재접속 직후 빈 배열) 라이브 레코드 미반영 race 창에서 hasLiveCurrentRecord=false → before-anchor 트리밍 + grace 갭 제외 use-cumulative-elapsed.ts:71-123 · page.tsx:338-371(anchor 갱신) 게스트 재접속 경과시간 감소
모니터 재접속 후 경과시간 2배 점프(09:08→18:03) LogRocket disconnect 직후 Sessions loaded {count: 1} (0→1) 종료 세션(duration!=null) 로드 시 dedup 플래그(liveCountedFromFetch) 미설정 → 이중 가산 use-cumulative-elapsed.ts:254-268 (dedup 루프 duration!=null 경로 miss) 이중가산 모니터 재접속
재접속 시 이탈시간 규칙 미반영 + 회귀 gap 규칙: ≤30초 포함 / >30초 제외 서버가 ≤30초 재접속에서 disconnectedAt 대신 Date.now()로 종료 → 미적용 connection-handlers.ts(exitedAtOverride) · use-cumulative-elapsed.ts(finalize 클램프) 이탈시간 규칙·재접속 회귀
(메타) 회귀 재현경로 — 결정론 검증 과정 산술 하네스 ③번 케이스 → 149s(02:29) 정확 재현 race 창(라이브 레코드 부재) + before-anchor 트리밍 + grace 갭 use-cumulative-elapsed.ts:58-123 · lesson-session.service.ts:93,107,114,149-150 누적시간 회귀 재현경로

관련 코드흐름 → 누적 경과시간 추적·세션 합산

📝 녹음·캡션(STT) 누락·어긋남

증상(신고 표현)즉시 확인의심 원인코드 위치분석 문서
TTS 모드에서 아동 캡션 누락 + 캡션 위치 어긋남 caption.json role 분포(고장: assistant 54·user 0 / 정상: 71·49) External STT가 아동 전사를 type:"text"/"stt_verified"로 emit하나 녹음 수집기는 type==="audio"만 수용 session-handlers.ts:47-73 · use-ai-session.ts:611-624 캡션 위치 어긋남·아동 캡션 누락
ppi-socket WARN 폭주(End of file) Loki ffprobe duration ... failed: End of file ~1,224건/24h(warn의 45%) producer 교체 시 빈/짧은 OGG 생성 — 오디오는 size>0 필터, 캡션 probe는 필터 없이 전부 probe recordingManager.ts:1064(collectSegment) · recordingManager.ts:229-235(buildAndUploadCaptions) ffprobe WARN 빈 OGG

관련 코드흐름 → 녹음 파이프라인 · STT 배치 서버 · STT 오디오 처리 세션 · 세션 로그 시스템 · External STT 클라이언트 · STT 폴백

🛠️ 녹음 후처리 부하(서버)

증상(신고 표현)즉시 확인의심 원인코드 위치분석 문서
녹음 후처리 CPU spike, mediasoup 워커 부하 Grafana 워커 ru_utime 그래프 · transcode/ffprobe 동시 spawn 로그 세마포어 over-admission(maxConcurrency 위반) + 무제한 병렬 ffprobe + dead-port RTP 포워딩 낭비 recordingManager.ts(TranscodeSemaphore, buildAndUploadCaptions Promise.all) · metrics.ts:116-120 녹음 후처리 CPU Spike

관련 코드흐름 → 녹음 파이프라인 · 관측성(Prometheus·Loki·Grafana)

🧑‍🎤 아바타 매칭·립싱크

증상(신고 표현)즉시 확인의심 원인코드 위치분석 문서
아바타 talking 전환 시 잠깐 다른 아바타가 나타남(게스트측) LogRocket avatarId 추이 vs 렌더된 talking 파일명 불일치 useAvatarResources가 avatarId 변경 시 이전 리소스를 즉시 비우지 않아 stale 윈도우 발생 use-avatar-resources.ts:57-93 · use-avatar-video.ts:61-74 아동005 27회기 아바타 매칭

관련 코드흐름 → 아바타 RMS 립싱크(canvas) · 아바타 입모양 개선 검토

🌐 네트워크 품질·단절

증상(신고 표현)즉시 확인의심 원인코드 위치분석 문서
콘솔에 httpbin 503 + CORS 에러 10초 주기 반복 LogRocket httpbin.org/status/200 503 응답 · S3 다운로드는 정상인지 병행 확인 ☠️ 외부 무료 서비스 httpbin.org의 503 + 503 응답에 CORS 허용 헤더 부재 use-network-quality.ts(measureExternalLatency) · restHandlers.ts:441 httpbin 503·CORS

관련 코드흐름 → 게스트 입장 플로우(canEnter) · 수업 입장 제어

🔔 알림 프리셋 동기화

증상(신고 표현)즉시 확인의심 원인코드 위치분석 문서
첫 트리거 미발생 / 표시 중 이미지 교체 / 진행자·아동 이미지 불일치 소켓 로그: HOST_SET_AMBIENT_NOISE_TEMPLATE(Redis, 느림) vs host-session-message(직행) 도착 순서 스냅샷(Redis 경유)이 트리거(직행)보다 늦게 도착하는 race use-guest-page-session.ts · broadcast-ambient-template.ts · use-ambient-noise-alert-store.ts 알림 프리셋 트리거·이미지 동기화

관련 코드흐름 → 아동 알림 프리셋 동작 흐름 · 알림 프리셋 생성·관리

🔌 AI 세션 시작 실패

증상(신고 표현)즉시 확인의심 원인코드 위치분석 문서
OpenAI Realtime 세션 시작 실패 — The string did not match the expected pattern. WebRTC setRemoteDescription 실패 로그 · answer.type · answer.sdp 시작(v= 여부) · SDP 길이 브라우저가 OpenAI 서버 SDP answer를 파싱하다 실패한 런타임 에러(instruction 문제 아님) await pc.setRemoteDescription(answer) 후속(로그 보강 필요) · /api/realtime/call OpenAI Realtime 세션 시작 실패

관련 코드흐름 → OpenAI Realtime 세션 매니저 · Auth 세션·TURN/ICE 발급

이 매트릭스는 bugs/의 개별 분석을 증상 축으로 재배열한 색인이다. 새 증상 분석이 추가되면 해당 군 표에 한 행을 더하고, 새 증상군이 생기면 빠른 색인에 항목을 추가한다. 재현이 필요한 단발 신고는 /repro-path 스킬 → 재현 경로 파악 에이전트 설계 참고.