🤖 에이전트 설계안 v1 📦 PPI-1194 S3 세션 로그 🎬 영상 자동전환 고질 이슈

S3 세션 로그 · Grafana · 자동전환 분석 에이전트 설계 v1

마지막 업데이트 2026-08-19

목표는 “LogRocket에 흩어진 진행자/아동 로그 + PPI 웹에서 내려받는 S3 병합 로그 + Grafana Loki 서버 로그”를 한 번에 교차 분석해, 영상재생 스텝 자동전환 실패를 재현 가능한 조건·타임라인·의심 코드 라인으로 자동 환원하는 개발 코치형 에이전트를 만드는 것이다.

0 한 줄 공약 타이틀

“로그를 모으는 엔지니어에서, 로그가 스스로 재현경로를 말하게 만드는 엔지니어로.”

S3 로깅 업로드 시스템은 단순 보관 기능이 아니라 AI 분석의 1차 데이터 레이크다. 이 위에 Grafana·LogRocket·코드 검증 루프를 얹는다.

1 현재 코드 기준 데이터 소스

데이터	현재 코드 진입점	에이전트가 읽는 신호
S3 세션 로그 파트	`use-lesson-log-collector.ts:39-119`, `use-lesson-log-uploader.ts:48-99`	guest/monitor별 console·logger·전역 error를 NDJSON part로 수집·업로드
종료 시 final flush	`use-lesson-log-uploader.ts:138-166`, `app/api/lesson-logs/append/route.ts:13-78`	pagehide/visibilitychange 직전의 마지막 로그. keepalive 단발 POST라 누락 리스크도 별도 체크
병합 아카이브	`lesson-log-merge.ts:59-133`, `lesson-logs/finalize/route.ts:35-103`	role/sessionId/instanceId/seq를 붙여 timestamp 순서로 정렬된 단일 JSONL
PPI 웹 다운로드	`lesson-log-archive-section.tsx:113-124`, `download-url/route.ts:31-48`	선택 회기 최신 runDate의 presigned downloadUrl
Grafana/Loki	`apps/socket/src/sfu-socket/handlers/session-handlers.ts:791-815` 등	`Guest video play started`, `Guest video ended`, step update, disconnect, mediasoup producer/consumer
영상 자동전환 클라이언트	`guest-layout-content.tsx:159-164`, `meet-video.tsx:512-526`, `video-end-watchdog.ts:141-182`	ended/watchdog/onEnd → notifyVideoEnd + goToNextStep 경로가 실제 호출됐는지

2 에이전트 구성

orchestrator Repro Coach
Slack 입력을 이슈 스펙으로 정규화하고, 로그 수집·상관분석·코드검증·반증 루프를 지휘한다.

collector Session Log Collector
PPI 웹 또는 S3 key/downloadUrl로 병합 JSONL을 확보하고 role/sessionId/instanceId별로 분리한다.

collector Grafana Loki Collector
roomId와 KST 시간창으로 ppi-socket 로그를 조회해 서버 관점 타임라인을 만든다.

collector LogRocket Pair Finder
아동/진행자 세션 링크와 주요 사용자 행동을 찾고, S3 로그와 roomId·시간으로 매칭한다.

analyst Video Transition Analyst
MEET_VIDEO·RESOURCE_CACHE·guest-video-end·guest-step-update 신호를 자동전환 판정표로 분류한다.

refuter Hypothesis Refuter
“onEnd 미호출” “socket emit 실패” “host/monitor 반영 실패” 가설을 반례 기준으로 기각/유지한다.

3 v1 파이프라인

인테이크
입력: 아동명/회기/대략 시각/KST/증상/가능하면 roomId. 없으면 LogRocket·S3 로그 후보로 찾는다.

▼

증거 수집
S3 병합 로그 다운로드 → LogRocket 아동·진행자 세션 매칭 → Grafana ppi-socket query_range. 세 소스 모두 roomId와 시간축으로 정렬한다.

▼

자동전환 판정
클라이언트 로그에서 Video play/canplay/timeupdate/ended/watchdog와 Notifying video ended, Moving to next step를 찾고, 서버 로그에서 guest-video-end, Guest step update를 찾는다.

▼

코드 경로 검증
실제 코드 라인 기준으로 “어떤 gate가 안 열렸는지” 확인한다. 예: MeetVideo.handleEnded 미호출, VideoEndWatchdog progressed 조건 미충족, autoTransitionEnabled false/stale.

▼

반증 루프
동일 로그가 다른 원인을 가리키는지 검사한다. 예: guest-video-end는 있는데 guest-step-update가 없으면 onEnd가 아니라 step sync 문제다.

▼

산출
Slack용 요약 + 재현 단계 + 의심 파일/라인 + 추가 계측 PR 제안 + 필요 시 ppi-docs HTML 문서.

4 자동전환 실패 판정표

로그 패턴	판정	우선 코드
`Video play/canplay` 있음, `Video ended`/`watchdog backstop`/`guest-video-end` 없음	게스트 클라이언트 onEnd 미도달	`meet-video.tsx`, `video-end-watchdog.ts`
`Video ended` 또는 `watchdog backstop` 있음, `guest-video-end` 없음	notifyVideoEnd/socket uplink 누락	`guest-page-session`, socket emit 경로
`guest-video-end` 있음, `Moving to next step`/`guest-step-update` 없음	자동전환 gate 또는 goToNextStep 문제	`guest-layout-content.tsx:159-164`, autoTransition 상태
`guest-step-update` 서버 도달, 진행자만 화면 미변경	host/monitor 수신·렌더링 문제	monitor-dashboard/focus-view listener
진행자 수동 전환 후에만 step update	자동전환 실패 재현 강한 후보	게스트 video end → step update 체인 전체

5 v1 구현 백로그

S3 JSONL 파서 CLI: 다운로드한 병합 로그를 읽어 role/sessionId/ctx/msg 기준으로 필터링하고 KST 타임라인 출력.
Grafana query template: roomId + ±15분으로 ppi-socket 로그를 자동 조회하고 영상 자동전환 키워드만 추출.
판정 엔진: 위 판정표를 코드화해 “onEnd 미도달 / socket 미도달 / step sync 실패 / monitor 반영 실패” 중 하나로 라벨링.
코드 라인 매퍼: 판정 라벨별로 반드시 읽을 파일과 라인 범위를 출력해 추측을 막는다.
리포트 생성기: Slack 10줄 요약 + 상세 HTML 문서를 동시에 생성한다.

6 철수에게 필요한 운영 습관

이슈가 오면 “아동명/회기/대략시각/증상/roomId 있으면 roomId”를 한 줄 템플릿으로 남긴다.
수업 후에는 PPI 웹에서 세션 로그 병합/다운로드가 되는지 확인한다. S3 로그가 있으면 AI 분석 정확도가 크게 올라간다.
자동전환 실패는 “영상이 재생됐는지”보다 “게스트가 영상 종료를 앱에 알렸는지”가 핵심이다. guest-video-end와 guest-step-update를 반드시 분리해서 본다.