소켓 서버 로그 수업별 집계용 roomId·direction 추가

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

1ecfdac7 charles-na · 2026-11-06 Feature 9 files +296 −8

PR #1285 (PPI-1441). ppi-socket의 Host changed step(활동 전환·새로고침), Host cancelled AI response(말하기 멈춤) 같은 로그에 수업 식별값이 없어 KR2(양호 수업 비율)를 수업 단위로 셀 수 없었습니다. 10개 로그의 data에 roomId({아동ID}_{회기})를 넣고, 활동 전환 로그에는 direction(prev/next/jump/refresh)을 더해 새로고침과 전환을 나눠 셀 수 있게 했습니다. 바뀐 것은 로그 출력뿐이고 화면 동작은 그대로입니다. 리뷰 시 먼저 볼 곳은 direction 허용값 처리와 Peer left room의 roomId 선택입니다.

무엇이, 왜 바뀌었나

강제퇴장 로그에는 이미 roomId가 있었지만 다른 이벤트에는 없어서, 이벤트마다 수업별 집계 가능 여부가 달랐습니다. 이번 변경으로 KR2 대상 이벤트의 서버 로그를 같은 키로 묶어 셀 수 있습니다.

흐름 — 활동 새로고침이 서버 로그에 남기까지

1

진행자 "활동 새로고침" 클릭 → handleRefreshCurrentStep

apps/web/hooks/client-host/use-step-selection.ts

direction: "refresh"로 emitStepChange 호출 (next/prev/jump도 같은 함수를 거침)

2

host-step-changed emit에 direction 포함

apps/web/features/session-control/api/emit-step-change.ts

3

서버 권한 검사 → 로그에 roomId·direction(허용값만) 기록 → 아동에게 기존 payload 전달

apps/socket/src/sfu-socket/handlers/session-relay-handlers.ts

코드로 보는 핵심 지점

1. direction은 허용값만 로그에 남는다

apps/socket/src/sfu-socket/handlers/session-relay-handlers.ts const HOST_STEP_CHANGE_DIRECTIONS = new Set(["prev", "next", "jump", "refresh"]); function normalizeHostStepChangeDirection(value: unknown): string | undefined { return typeof value === "string" && HOST_STEP_CHANGE_DIRECTIONS.has(value) ? value : undefined; } logger.info("Host changed step", { roomId, direction: normalizeHostStepChangeDirection(direction), stepType,

클라이언트가 임의 문자열을 보내도 로그 필드가 오염되거나 카디널리티가 폭증하지 않습니다. 아동에게 전달하는 emitRoomEventWithoutMonitorSockets(... "host-step-changed", {...}) 내용에는 direction을 추가하지 않았습니다.

2. 웹 → 소켓 payload에 direction 추가

apps/web/features/session-control/api/emit-step-change.ts socket.emit("host-step-changed", { roomId, ... stepIndex, direction, });

3. Peer left room — 모니터 퇴장도 입장 로그와 같은 방 번호를 남김

apps/socket/src/sfu-socket/handlers/connection-handlers.ts logger.info("Peer left room", { role: peerInfo.role }); logger.info("Peer left room", { roomId: peerInfo.joinedRoomId || peerInfo.roomId, role: peerInfo.role, });

모니터 peer는 roomId가 null이고 관찰 중인 방은 joinedRoomId에 있습니다. 그래서 바로 위 decrementPeerCount와 같은 식을 씁니다.

레이어별 변경 요약

레이어파일핵심 변경
Webfeatures/session-control/api/emit-step-change.tshost-step-changed에 direction 추가
Socketsession-relay-handlers.tsroomId 4종 + direction 허용값 처리
Socketavatar-handlers.tsHost cancelled AI response에 roomId
Socketsession-alert-handlers.tsGuest issue report accepted · Guest auto-finish에 roomId
Socketconnection-handlers.tsPeer joined/left room · Continued live lesson session에 roomId
Testsocket 3개 + emit-step-change.test.ts(신규)console.log 구조화 로그를 파싱해 roomId·direction 검증, 허용되지 않은 direction이 로그·아동 전달 양쪽에 없는지 확인

리뷰 관전 포인트

집계 주의

Peer joined room/Peer left room은 모니터 입장·퇴장도 같은 roomId로 남깁니다. 아동 입장만 셀 때는 role: "guest"로 걸러야 합니다.

구조

roomId 형식은 createRoomId(userId, lessonIndex) = {아동ID}_{회기}입니다. 강제퇴장 로그는 roomId를 data가 아닌 msg 문자열(Guest force kicked from room ${roomId})에 넣고 있어, 집계 쿼리에서 다르게 다뤄야 합니다. 강제퇴장 로그는 이번 범위가 아닙니다.

미포함

듣기 ON/OFF 로그(voice_control_command)에는 여전히 roomId가 없습니다. 지금은 type·stage·outcome만 남습니다. 대상 표에 없어서 이번에는 고치지 않았습니다.

영향 범위

화면에 보이는 동작은 바뀌지 않았습니다. 로그 msg 이름도 그대로라서 기존 Grafana 검색은 계속 동작합니다. 웹과 소켓 중 어느 쪽을 먼저 배포해도 호환되지만, 둘 다 배포되기 전에는 direction 없는 로그가 남습니다.

검증

새로 넣은 테스트는 모두 수정 전 실패, 수정 후 통과를 확인했습니다. socket 전체 테스트는 866개 통과, 25개 실패이고, 실패 25개는 수정 전 코드에서도 똑같이 실패합니다(time-end-request-state·router-manager-guest-state·runtime-secret-deployment-wiring). mutation 테스트는 이 기존 실패 때문에 사전 실행 단계에서 멈춰 결과가 없습니다. 실제 수업에서 Loki 로그는 아직 확인하지 않았습니다.

관련 문서

관련 문서: KR2 양호 수업 진행 비율 — 로그 기반 지표 검토 — 이 PR이 서버 로그 쪽 집계 공백(활동 새로고침·말하기 멈춤·도움 요청)을 메움

관련 문서: 진행자 "연결 불안정" 기록 527건 · 세션로그 대조와 아동 영향 — 수업 단위 이벤트 집계 분석 사례

관련 문서: 자동전환 미반영 — 게스트 socket.io 업링크 stall 원인 분석 및 로깅 추가 — host-step-changed 경로와 소켓 서버 로깅