PPI 데일리 수업 기술 건강률

마지막 업데이트 2026-11-04

현재 계측만으로 ‘문제 없는 수업 비율’을 정직하게 산출할 수 있는지, 그리고 Web·Socket·LiveKit Agent에 무엇을 보강해야 하는지 정리합니다.

검토 기준일 2026-11-04 · 소스 기준 checkout: develop · 범위: apps/web, apps/socket, apps/livekit-agent

결론

현재: 부분적으로 문제 징후를 찾을 수 있으나, 일별 양호 비율의 신뢰 가능한 분자·분모는 아직 바로 산출할 수 없습니다.
Web 쪽 수업 로그 아카이브, 네트워크/미디어 경고, socket 운영 메트릭, LiveKit agent 이벤트는 각각 존재합니다. 하지만 로그 업로드는 기본 비활성일 수 있고, 각 신호가 같은 ‘수업 1건’ 식별자와 판정 규칙으로 모이지 않습니다. 무로그는 정상 증거가 아니며, 로깅 미활성·업로드 실패·로그 소실일 수도 있습니다.

따라서 11/3의 “347건 중 무이슈 수업 비율”은 현재 코드 확인만으로 숫자를 확정할 수 없습니다. 347이라는 분모의 기준과 실제 날짜별 데이터가 주어지지 않았고, 운영 로그/DB를 조회하지 않았습니다.

1. 현재 구조에서 확인 가능한 근거

PPI Web — 클라이언트 증거게스트와 모니터 화면에서 error/warn, 전역 JS 오류·미처리 Promise·리소스 로드 실패를 버퍼에 모아 S3 세션 로그(JSONL)로 보낼 수 있습니다. guest collector는 수업 화면이 terminal이 아닐 때 활성화되고, monitor collector는 guest가 붙어 있을 때 활성화됩니다. 기본 uploadEnabled=false이므로 전역 설정/환경/개발 override 확인이 선행돼야 합니다.
PPI Socket — 서버·SFU 증거room join/leave, disconnect, 미디어 transport 오류와 guest 이슈 리포트 로그가 있습니다. Prometheus에는 연결/해제·활성 룸·guest lifecycle·transport 생성 결과 등 집계 메트릭이 있습니다. 다만 대부분 room/session ID를 metric label로 쓰지 않아 개인별 수업을 역추적하는 데이터셋이 아닙니다.
LiveKit Agent — 런타임 증거agent 측 lifecycle/event 진단·voice session 및 turn correlation 기반 로그가 있습니다. 개별 STT/TTS/agent 처리 오류나 readiness 증거를 찾는 데 도움은 되지만, Web의 userId/lessonIndex 및 socket room/session과 안정적으로 연결된 수업별 결과 원장인지 별도 확인이 필요합니다.

코드에서 확인한 지점

2. 347건 일별 비율에 필요한 정의

무이슈 수업 비율(%) = eligible 수업 중 기술 이슈 이벤트가 0건인 수업 수 ÷ eligible 수업 수 × 100

먼저 분모를 “해당 KST 날짜에 실제 시작 버튼을 눌러 시작이 확정된 고유 수업”으로 고정하는 것을 권장합니다. 수업 단위 키는 최소 lessonId 또는 userId+lessonIndex + runDate + lessonSessionId여야 합니다. 재접속·활동별 AI session은 새 수업 분모로 세지 말고 같은 lesson session에 합쳐야 합니다. 테스트/취소/미시작은 명시적 제외 사유로 분리합니다.

347이 이미 확정된 eligible 분모라면, 날짜 범위(KST), 테스트 제외, 재수업/재입장 중복 제거 기준을 보존한 상태로 이슈 수업 수를 판정해야 합니다. 단순히 347에서 error 로그가 없는 건을 빼는 방식은 위험합니다.

판정은 3단계로 권장

  1. 차단(Blocked): 수업 진입/시작 불가, AI 세션 준비 실패가 지속, 핵심 오디오·영상 세션이 복구되지 않아 수업 진행 불가.
  2. 저하(Degraded): 미디어/AI/소켓 오류가 발생했으나 자동·수동 복구되어 수업은 진행; 예: 재연결, 재시도, 지연/일시 무음.
  3. 관측(Observed): 경고가 발생했지만 사용자 영향 미확인 또는 짧은 transient. 건강률 분자에서는 조직 정책에 따라 제외하거나 별도 공개.

공식 ‘양호’는 우선 차단·저하가 모두 없는 수업으로 두고, 관측 전용 수업 수와 데이터 커버리지(로그 수집 성공률)를 함께 보여주세요. 관측만으로 이슈 없음이라 결론 내리지 않습니다.

3. 보강 계측 제안

Web (guest + monitor)수업 lifecycle event: 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 성공 여부도 남깁니다.
Socket / SFUlesson-session 단위의 입장 승인/거절, join/leave/disconnect/reconnect, room instance redirect, send/recv transport 및 producer/consumer lifecycle, 오류코드·복구 결과를 구조화합니다. 기존 저카디널리티 Prometheus metric은 전체 추세·알람에 유지하고, lessonSessionId/roomId/peerId/producerId는 Loki event payload에 두어 metric label 폭증을 피합니다. 수업 종료 시 correlation key와 함께 서버 관찰 결과를 요약합니다.
LiveKit Agentdispatch accepted/failed, worker/job start, room connect, participant/agent ready, first input, first response/audio, STT/TTS errors·latency, session end 및 job failure를 같은 수업 correlation key로 기록합니다. Agent event의 voice_session_id/turn_id는 lesson session과 매핑하고, app-level terminal state/오류 코드를 추가해 worker 미배정·세션 시작 실패를 일반 timeout과 구분합니다.
공통 규칙: 사용자 발화/대화 원문, 인증 토큰, 개인정보는 지표에 넣지 않습니다. metric label은 고정 enum만 허용하고, 개별 correlation ID는 접근제어된 로그/DB event에 보관합니다. 수업 마감 후 서버 측에서 idempotent roll-up을 만들고, 각 수업의 결과 + 근거 이벤트 목록 + 판정기 버전을 함께 저장합니다.

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는 실제 운영 데이터를 조회해 계산해야 하며 본 검토에서는 산출하지 않았습니다.

운영 가능하게 만드는 최소 게이트

  1. 시작/종료의 정본 이벤트와 분모 정의를 확정하고 KST runDate를 서버가 계산.
  2. 수업 식별자 교차 매핑: Web lessonSessionId ↔ Socket roomId/guest connection ↔ LiveKit voice_session_id/job/room.
  3. 이슈 catalogue, severity, transient/recovery window, duplicate suppression을 버전 관리.
  4. logging enabled 여부, upload/drop 비율, event coverage를 별도 수치화. 로그 누락 수업은 healthy가 아니라 unknown.
  5. 과거 하루 표본을 수작업 판정해 룰의 오탐·누락을 검증한 뒤 일별 자동 리포트를 활성화.

5. 최종 판단과 다음 단계

검토 범위는 코드 구조와 로그 emitter 중심입니다. 운영 환경에서 logger 수집/보존/배포 설정과 실제 11/3 데이터를 확인하지 않아 현재 production coverage 수치는 확정하지 않습니다.