🧭 ppi-bug-tracer · 재현 경로 분석 방식

이슈를 받으면 “원인 추측”이 아니라 “재현 가능한 경로”로 좁힌다

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

문서 읽는 법 · 활용 가이드식

이 문서는 이렇게 읽으면 됩니다

PPI 재현 경로 파악 흐름 시각화의 핵심을 활용 가이드식으로 먼저 안내합니다. 기술적 결론과 원문 근거는 아래 본문에 보존되어 있습니다.

핵심 흐름 펼쳐 보기

어떤 상황에서 이 문서를 쓰는지 확인합니다.
절차와 판단 기준을 순서대로 적용합니다.
기대 산출물과 운영 체크리스트로 결과를 확인합니다.

전체 파이프라인 한눈에 보기
자료가 들어오는 통로
증상별로 먼저 보는 코드 지도

PPI 이슈 분석은 신고 문장 하나를 바로 결론으로 바꾸지 않는다. LogRocket, Grafana, 실제 코드 라인, 반증 루프를 거쳐 “어떤 조건이 동시에 만족될 때 동일 증상이 다시 발생하는가”를 단계별 재현 레시피로 만든다.

1증상 도메인 라우팅

2아동·진행자 로그 대조

3코드 라인 단위 검증

4반례 통과 후 재현 경로 확정

핵심 원칙

코드를 읽기 전에
재현 경로를 확정하지 않는다.

로그는 관찰 단서, 코드는 가능 조건, 반증은 확정 전 필수 관문이다.

최종 산출물은 “원인 단정”이 아니라 “재현 가능한 절차”

전제 조건: 환경, 역할, roomId, sessionId, 브라우저/기기 조건
재현 단계: 어느 시점에 어떤 조작을 해야 하는지
예상 결과와 실제 결과
의심 파일/라인과 왜 그 분기가 증상을 만드는지
그냥 따라 하면 실패하는 race window·자가복구·반례 조건

전체 파이프라인 한눈에 보기

이슈 수신

증상, 아동명, 날짜, 환경, 화면, 역할, 세션 URL을 받는다.

입력 정리

증상 라우팅

guest, meet, monitor, SFU, OpenAI, 채팅, 타이머 등 도메인으로 분기한다.

탐색 범위 결정

로그 확보

LogRocket 아동·진행자 세션과 Grafana socket/SFU 로그를 시간순으로 모은다.

관찰 단서

1차 가설

A 이벤트 → B 상태 → C 코드 분기 → D 증상 형태로만 가설화한다.

아직 미확정

코드 검증

route → hook → manager → socket/API 흐름을 따라 gate 조건과 라인을 찾는다.

라인 번호 확보

반증 루프

정상 세션, 반례 조건, 로그 순서 불일치 가능성으로 가설을 깨본다.

기각/수정/유지

재현 최소조건

동시에 만족되어야 하는 조건과 race window, 자동복구 타이밍을 좁힌다.

필요조건 추출

레시피 산출

결정론적 하네스 또는 E2E 조작 절차로 재현 경로를 문서화한다.

최종 답변

입력/증상 탐색/관찰 코드 검증 재현 확정

자료가 들어오는 통로

🧒 LogRocket
아동 세션

URL/행동/guest, /client-guest/session, 클릭, 입장, 장치 선택

ConsoleAI audio, MeetVideo, device, socket 로그

NetworkAPI 실패, 지연, 재시도, 4xx/5xx

시간축증상 발생 직전/직후 이벤트 순서

👩‍🏫 LogRocket
진행자/호스트 세션

화면meet, monitor-dashboard, focus-view

알림issue report, force kick, monitor alert

상태guest state, timer, chat, media status

대조아동 세션과 roomId/lessonIndex 매칭

📈 Grafana / ppim
서버 로그

Socketjoin, leave, disconnect, reconnect

SFUproducer, consumer, transport lifecycle

식별자roomId, socketId, producerId, consumerId

순서아동 Producer ↔ 진행자 Consumer 상태 대조

💻 PPI 코드

Routeguest / meet / monitor 진입점

Hookuse-session-manager, use-ai-session, media manager

Eventsocket emit/on, cleanup, retry, debounce

Gateif, 상태 플래그, null, race window

증상별로 먼저 보는 코드 지도

🔊 AI 오디오 무음

아동이 “소리가 안 들려요”를 눌렀는지
audio play 성공 로그가 실제 가청 성공을 보장하는지
currentTime, packetsReceived, audioEnergy가 있는지

guest-entry → use-device-manager → use-ai-session / use-session-manager → guest socket → monitor alert

🎥 활동 영상 / 리소스 미표시

loadedmetadata/canplay/play와 실제 프레임 표시를 분리
timeupdate/ended/guest-video-end 유무 확인
spinner, overlay, z-index, layoutMode 조건 확인

MeetVideo → use-resource-cache → guest-layout-content → step sync → socket video end

📡 SFU / WebRTC 연결

아동은 Producer, 진행자는 Consumer로 구분
transport connect, consume, resume, close 순서 확인
producer는 살아있고 consumer만 닫혔는지 확인

use-media-manager → ICE → mediasoup client → socket SFU handler → Grafana logs

🚪 입장 / 승인 / 방 상태

guest와 host가 같은 roomId에 들어갔는지
입장 승인 이벤트와 상태 업데이트 순서 확인
disconnect/reconnect grace period 확인

/app/guest → /app/main/meet/[roomId] → socket room events → room state

⏱️ 타이머 / 누적시간 점프

클라이언트 추정 시간과 서버 상태가 갈라지는 지점
polling/refetch, hidden tab, reconnect 후 보정 확인
정상 반례의 계산식 확인

monitor-dashboard / focus-view → cumulative elapsed hook → API polling/refetch

💬 채팅 / 프리셋 / API

socket chat 이벤트와 DynamoDB/API 응답 분리
optimistic update와 실제 저장 상태 대조
네트워크 실패 후 재시도/중복 전송 확인

chat hook → preset API → socket chat event → DynamoDB service

가설을 확정하는 기준

✅ 확정

코드 실행 또는 하네스/E2E로 재현됨.
로그의 상태 전이를 같은 순서로 주입했을 때 신고 증상이 다시 나온다.

🟠 강한 후보

로그와 코드가 일치하지만 실행 재현 전.
라인 단위 근거는 있으나 실제 브라우저/라이브 스택 재현은 아직이다.

⚪ 보류

권한, 세션, raw 로그, 환경 부족.
추가 LogRocket Export, Grafana 인증, 비교 세션 등이 필요하다.

재현 경로 파악 요청 예시

정보가 적을 때

📝 최소 요청

아동070 1회기에서 진행자 쪽에 아동 소리가 안 들렸대.
재현 경로 파악해줘.

세션 정보가 있을 때

🔎 LogRocket 포함 요청

아동070 1회기 / 2026-06-20 16:30 KST / prod.
아동이 말했는데 진행자에게 안 들렸다는 이슈야.
LogRocket 아동·진행자 세션과 Grafana SFU 로그를 대조해서
재현 경로를 찾아줘.

증상 도메인이 명확할 때

🎥 영상 재생 이슈 요청

아동005 27회기에서 활동 영상이 play 로그는 있는데
아동 화면에서는 안 넘어간 것 같아.
MeetVideo, resource cache, guest-video-end 흐름 기준으로
재현 조건과 반례까지 정리해줘.

검증 방식까지 원할 때

🧪 E2E 레시피 요청

monitor-dashboard에서 타이머가 뒤로 튄다는 제보야.
코드 라인 근거와 함께,
실제 브라우저에서 재현하려면 어떤 네트워크 throttle/소켓 끊김을
몇 초 window에 넣어야 하는지 E2E 레시피로 써줘.

❌ 아쉬운 요청

어제 수업에서 이상했대. 원인 찾아줘.

✅ 좋은 요청

2026-06-20 16:30 KST prod, 아동070 1회기.
증상: 진행자 쪽에서 아동 소리가 안 들림.
확인할 것: 아동/진행자 LogRocket 세션, Grafana SFU 로그,
아동 Producer ↔ 진행자 Consumer 이벤트 순서,
코드 라인 근거, 최종 재현 단계.

최종 답변에 반드시 들어가는 것

이슈 요약: 증상, 화면, 역할, 시간대
관찰 단서: LogRocket 아동/진행자 세션, Grafana 로그
코드 검증 결과: 파일과 라인 번호
반증 루프: 유지/부분수정/기각 판정
최종 재현 경로: 전제 조건과 단계
결정론적 재현 또는 E2E 레시피
재현 함정: race window, 자동복구, 반례
추가 확인 필요 사항

재현 경로 산출 형태

전제 조건
1. 같은 roomId에서 아동과 진행자가 연결되어 있다.
2. 특정 이벤트가 N초 안에 발생한다.
3. 코드상 gate 조건이 false/undefined 상태로 남는다.

재현 단계
1. 아동 세션에서 A 조작을 수행한다.
2. 진행자 세션에서 B 상태가 되도록 한다.
3. 네트워크/소켓/미디어 조건 C를 만든다.
4. D 로그가 찍힌 직후 화면을 확인한다.

예상 결과
- 정상이라면 E 이벤트가 발생하고 자동복구된다.

실제 결과
- F 분기로 들어가며 G 증상이 재현된다.

의심 파일/라인
- apps/web/...:123 — gate 조건
- apps/socket/...:456 — 이벤트 순서