PPI 데일리 수업 기술 건강률
마지막 업데이트 2026-11-04
현재 계측만으로 ‘문제 없는 수업 비율’을 정직하게 산출할 수 있는지, 그리고 Web·Socket·LiveKit Agent에 무엇을 보강해야 하는지 정리합니다.
결론
Web 쪽 수업 로그 아카이브, 네트워크/미디어 경고, socket 운영 메트릭, LiveKit agent 이벤트는 각각 존재합니다. 하지만 로그 업로드는 기본 비활성일 수 있고, 각 신호가 같은 ‘수업 1건’ 식별자와 판정 규칙으로 모이지 않습니다. 무로그는 정상 증거가 아니며, 로깅 미활성·업로드 실패·로그 소실일 수도 있습니다.
따라서 11/3의 “347건 중 무이슈 수업 비율”은 현재 코드 확인만으로 숫자를 확정할 수 없습니다. 347이라는 분모의 기준과 실제 날짜별 데이터가 주어지지 않았고, 운영 로그/DB를 조회하지 않았습니다.
1. 현재 구조에서 확인 가능한 근거
uploadEnabled=false이므로 전역 설정/환경/개발 override 확인이 선행돼야 합니다.코드에서 확인한 지점
apps/web/lib/lesson-log-config.ts:21-28— 수업 로그 기본값은 20초 업로드 간격, 256KB 청크, debug 이상 수집, 업로드 OFF.apps/web/lib/lesson-log-sink.ts:28-89, 91-99— console.error/warn과 window error, unhandledrejection, resource error를 버퍼에 기록합니다. info/debug 전체 console은 자동 수집 대상으로 보장되지 않습니다.apps/web/hooks/use-lesson-log-collector.ts:41-98, 111-120, 144-180— 업로드 설정 조회, sink 설치, lesson context 설정/활성화 경로.apps/web/hooks/use-lesson-log-uploader.ts:57-107, 111-143, 146-173— presigned S3 업로드, 재시도 3회 후 청크 폐기, 종료 시 단발 keepalive flush.apps/web/widgets/guest/guest-layout/ui/guest-layout.tsx:117-127— guest 수업 화면에서 lesson log collector를 연결.apps/web/app/monitor-dashboard/[group]/[roomId]/page.tsx:799-823— guest 연결 중 monitor 로그 수집, 수업 완료 처리 연결.apps/web/app/api/lesson-logs/finalize/route.ts:35-38, 41-90— 로그 part를 runDate별 archive로 합치고 DynamoDB lesson에 archive metadata를 저장.apps/socket/src/metrics.ts:25-78, 116-117, 179-204— 운영 집계 metric들. 특히 live-room snapshot은 현재 활성 룸 상태이지 일별 종료 수업의 결과 분모가 아닙니다.apps/socket/src/mediasoup/transport-lifecycle-metrics.ts:31-48,apps/socket/src/sfu-socket/handlers/transport-handlers.ts:22-98— transport 생성 성공/실패 집계와 오류 로그.apps/socket/src/sfu-socket/handlers/session-alert-handlers.ts:238-300— guest 신고 수신·검증·monitor relay. 서버 로그는 신고 전문/diagnostic 값을 그대로 보존하지 않고 길이·유무 중심입니다.apps/livekit-agent/lifecycle_trace.py:29-100— voice session 기준 event ID와 turn/response correlation을 제공하는 agent 측 추적 기반. lesson 집계의 분모·판정 정의를 대신하지는 않습니다.
2. 347건 일별 비율에 필요한 정의
먼저 분모를 “해당 KST 날짜에 실제 시작 버튼을 눌러 시작이 확정된 고유 수업”으로 고정하는 것을 권장합니다. 수업 단위 키는 최소 lessonId 또는 userId+lessonIndex + runDate + lessonSessionId여야 합니다. 재접속·활동별 AI session은 새 수업 분모로 세지 말고 같은 lesson session에 합쳐야 합니다. 테스트/취소/미시작은 명시적 제외 사유로 분리합니다.
347이 이미 확정된 eligible 분모라면, 날짜 범위(KST), 테스트 제외, 재수업/재입장 중복 제거 기준을 보존한 상태로 이슈 수업 수를 판정해야 합니다. 단순히 347에서 error 로그가 없는 건을 빼는 방식은 위험합니다.
판정은 3단계로 권장
- 차단(Blocked): 수업 진입/시작 불가, AI 세션 준비 실패가 지속, 핵심 오디오·영상 세션이 복구되지 않아 수업 진행 불가.
- 저하(Degraded): 미디어/AI/소켓 오류가 발생했으나 자동·수동 복구되어 수업은 진행; 예: 재연결, 재시도, 지연/일시 무음.
- 관측(Observed): 경고가 발생했지만 사용자 영향 미확인 또는 짧은 transient. 건강률 분자에서는 조직 정책에 따라 제외하거나 별도 공개.
공식 ‘양호’는 우선 차단·저하가 모두 없는 수업으로 두고, 관측 전용 수업 수와 데이터 커버리지(로그 수집 성공률)를 함께 보여주세요. 관측만으로 이슈 없음이라 결론 내리지 않습니다.
3. 보강 계측 제안
lesson_started, entry_ready, ai_ready, media track/transport 상태, socket 연결/재연결, issue_detected, issue_recovered, lesson_ended. 모든 이벤트에 schemaVersion, lessonSessionId, runDate(KST), role, roomId, ts, eventId, subsystem, phase, outcome, severity, recoveryMs를 넣습니다. audio/video 실제 전송·재생 상태는 단순 play/connected 대신 packets/bytes/energy/frame 진행 증거를 제한 주기로 요약합니다. 수집기 활성/비활성, 청크 drop, upload/final flush 성공 여부도 남깁니다.lessonSessionId/roomId/peerId/producerId는 Loki event payload에 두어 metric label 폭증을 피합니다. 수업 종료 시 correlation key와 함께 서버 관찰 결과를 요약합니다.voice_session_id/turn_id는 lesson session과 매핑하고, app-level terminal state/오류 코드를 추가해 worker 미배정·세션 시작 실패를 일반 timeout과 구분합니다.4. 추천 데이터 흐름 및 일별 리포트
Web guest/monitor events ─┐
Socket/SFU lifecycle events ├─ lessonSessionId + roomId + eventId + UTC ts
LiveKit Agent events ─────┘
→ server-side append-only event store (S3/DynamoDB)
→ deduplicate & KST runDate normalize
→ per-lesson outcome: healthy | observed | degraded | blocked | unknown
→ daily numerator / denominator + coverage + breakdown by subsystem
집계 예시(형식만): 2026-11-03 | eligible=347 | healthy=H | degraded=D | blocked=B | observed=O | unknown=U | health_rate=H/347. H/D/B/O/U는 실제 운영 데이터를 조회해 계산해야 하며 본 검토에서는 산출하지 않았습니다.
운영 가능하게 만드는 최소 게이트
- 시작/종료의 정본 이벤트와 분모 정의를 확정하고 KST runDate를 서버가 계산.
- 수업 식별자 교차 매핑: Web lessonSessionId ↔ Socket roomId/guest connection ↔ LiveKit voice_session_id/job/room.
- 이슈 catalogue, severity, transient/recovery window, duplicate suppression을 버전 관리.
- logging enabled 여부, upload/drop 비율, event coverage를 별도 수치화. 로그 누락 수업은 healthy가 아니라 unknown.
- 과거 하루 표본을 수작업 판정해 룰의 오탐·누락을 검증한 뒤 일별 자동 리포트를 활성화.
5. 최종 판단과 다음 단계
- 현재 로그로 가능한 것: 수업별로 collector가 켜져 있고 archive가 남은 일부 건의 Web error/warn 조사, 특정 Socket/Agent 장애의 원인 분석, socket fleet 수준 운영 추세.
- 현재 로그로 불가능하거나 신뢰하기 어려운 것: 전체 일별 수업 분모 확정, 무로그 수업을 정상으로 판정, 모든 subsystem 이슈를 lesson 단위로 연결, 자동 복구된 저하와 관측 전용을 일관되게 분류.
- 필요 여부: 새 이벤트 수집·상관관계 키·수업별 roll-up이 필요합니다. 완전히 새 로깅 플랫폼을 만들기보다 기존 S3 lesson-log와 Loki/LiveKit event를 보완하고 server-side 결과 레코드를 추가하는 경로가 적절합니다.
- 실제 11/3 계산: 미실행. 11/3의 eligible 수업 목록/347 산출 근거, 해당 수업 archive 보유율, Loki·Agent 로그 접근 결과가 제공/조회되지 않았습니다.
검토 범위는 코드 구조와 로그 emitter 중심입니다. 운영 환경에서 logger 수집/보존/배포 설정과 실제 11/3 데이터를 확인하지 않아 현재 production coverage 수치는 확정하지 않습니다.