운영·메트릭¶

HTTP 관측 엔드포인트¶

GET /healthz: 의존성을 확인하지 않고 200 ok를 반환하는 프로세스 health
GET /metrics: Prometheus exposition

/healthz가 정상이어도 UDP 후보가 외부에서 도달하는지, /sohri 인증이 되는지, libopus 인코더가 실제로 동작하는지는 보장하지 않습니다. 배포 검증에는 SDP·ICE·오디오 synthetic session이 별도로 필요합니다.

표준 배포 가정¶

현재 Helm chart는 다음 구성을 표준값으로 설명합니다. 이는 바이너리의 필수 조건이 아니라 현재 GKE 배포 형태입니다.

미디어 전용 GKE Standard node pool의 hostNetwork: true DaemonSet
고정 외부 IP의 UDP passthrough Network Load Balancer
HTTPS 시그널링 Load Balancer와 별도의 UDP 미디어 경로
Pion 포트 범위와 LB backend/방화벽 UDP 범위 일치
GKE Managed Prometheus PodMonitoring
Secret Manager 사용 시 Workload Identity
preStop 5초와 앱 shutdown 10초를 포함하는 Pod 종료 예산 30초

다른 환경에서도 직접 UDP 도달성, 고유 포트 할당, 정상 DNS/TLS WSS 경로를 제공하면 실행할 수 있습니다. 외부 coturn은 선택 사항이며 자세한 제약은 시그널링·ICE·TURN에 있습니다.

핵심 메트릭¶

트래픽과 setup¶

메트릭	해석
`sohri_gw_active_sessions`	현재 등록된 WebRTC 세션
`sohri_gw_sessions_total`	생성된 세션 누계
`sohri_gw_sdp_requests_total`	SDP 요청 결과
`sohri_gw_session_setup_total`	단계·결과별 setup
`sohri_gw_session_errors_total`	세션 오류 분류
`sohri_gw_bridge_errors_total`	`/sohri` bridge 오류

sdp_requests_total 증가에 비해 sessions_total이 늘지 않으면 인증·SDP·encoder·ICE setup 단계를 label로 나눠 확인합니다. 활성 세션이 연결 종료 뒤 감소하지 않으면 lifecycle 누수를 의심합니다.

인바운드 RTP와 PCM¶

sohri_gw_inbound_rtp_packets_total, ...expected_packets_total, ...lost_packets_total
sohri_gw_inbound_rtp_sequence_events_total
sohri_gw_inbound_rtp_empty_payload_total
sohri_gw_inbound_decoded_frames_total, ...decode_errors_total
sohri_gw_inbound_rtp_timestamp_jumps_total, ...timestamp_jump_ms
sohri_gw_inbound_zero_runs_total, ...zero_run_ms, ...zero_samples_total
sohri_gw_inbound_pcm_bytes_total

RTP가 증가하는데 PCM byte가 늘지 않으면 payload type/Opus decode/입력 게이트를 확인합니다. 긴 zero run은 무음일 수도 있으므로 timestamp jump·packet loss와 함께 판단해야 합니다.

아웃바운드 품질¶

sohri_gw_outbound_reports_total, sohri_gw_rtcp_read_errors_total
sohri_gw_outbound_fraction_lost, sohri_gw_outbound_rtt_seconds
sohri_gw_outbound_jitter_seconds
sohri_gw_opus_loss_perc_applied_total, ...stale_total
sohri_gw_opus_encoder_info

RTCP receiver report가 없으면 adaptive loss feedback을 적용할 수 없습니다. SDP의 FEC 광고만 보고 활성으로 판단하지 말고 encoder info와 적용 loss percentage를 함께 확인합니다.

TTS·바지인¶

sohri_gw_tts_wav_rejected_total, sohri_gw_tts_discarded_total{reason}
sohri_gw_tts_stream_negotiation_total
sohri_gw_bargein_candidates_total{outcome}
sohri_gw_tts_duck_total, ...duck_ack_total, ...duck_ack_latency_seconds
sohri_gw_tts_duck_duration_seconds{reason}
sohri_gw_tts_pause_total{arm,trigger}, ...pause_duration_seconds{end_reason}
sohri_gw_tts_input_gate_*, ...input_preroll_flushed_bytes

duck ACK latency가 1초에 접근하거나 실패가 보이면 EPD 후보가 취소될 수 있습니다. pause 실험의 창 판정은 sohri_gw_tts_candidate_audible_offset_seconds이며, sohri_gw_tts_candidate_offset_seconds는 벽시계 참고값입니다. 두 분포를 바꾸어 해석하면 안 됩니다.

OpenAI backend engine¶

sohri_gw_openai_pcm_dropped_total{reason}
sohri_gw_openai_playout_underruns_total
sohri_gw_openai_playout_gap_seconds_total
sohri_gw_openai_frame_deadline_lateness_seconds

underrun에서 삽입한 무음은 timeline을 전진시키며 gap seconds에 기록됩니다. late_after_interrupt, queue_full, invalid_rate, stale_generation drop은 각각 원인이 다르므로 합계 하나로 알람하지 않습니다.

로그와 상관관계¶

구조화 로그는 Gateway session ID와 backend session ID를 구분해 사용합니다. credential, SDP, 사용자 음성 내용을 로그에 남기지 않습니다. 장애 분석 시 최소한 다음 순서로 상관시킵니다.

SDP request 결과와 Gateway session ID
/sohri 연결 및 backend session ID
PeerConnection state 전이
response ID, activity ID, playout generation
close 또는 shutdown 이유

TTS 디버그 캡처¶

통합 브랜치는 기간 한정 조사용 TTS GCS 캡처를 지원하지만 기본값은 꺼져 있습니다. TTS_DEBUG_CAPTURE=true이면서 bucket이 지정된 경우에만 동작하고 턴당 저장 시간 상한이 있습니다. 음성 데이터이므로 보존 기간·접근 권한·개인정보 정책을 승인한 조사에서만 켜고 종료 즉시 비활성화해야 합니다. 캡처 실패는 재생을 중단하지 않으며 별도 capture/upload 메트릭에 기록됩니다.

설정 이름과 기본값은 설정 참조, 증상별 절차는 테스트·문제 해결을 참고하세요.