llm-gateway-sub-backup/docs/ADR-5.md

ADR-005

• 제목: LLM Gateway의 로깅 로직 개선: 클라이언트 IP 및 포트 추출 방식 보강
• 날짜: 2025-07-29
• 상태: 채택됨 (Proposed)
• 작성자: [김용연 연구원]

---

1. 컨텍스트 (Context)

LLM Gateway에서 API 요청을 처리할 때, 로그에 기록되는 ip와 swagger_port 값이 프록시 환경에서 정확하지 않은 문제가 발생했다.

• 외부망 요청 시 request.client.host 값이 회사 공인 IP(프록시/NAT IP) 로만 기록됨.
• Host 헤더 기반 포트 추출이 실패해 "unknown"으로 로그에 기록되는 사례 발생.

---

2. 배경 (Background)

• 로드밸런서나 리버스 프록시(Nginx, ALB 등)를 거치는 구조에서, 원래 클라이언트 정보를 담은 헤더(X-Forwarded-For, X-Real-IP, X-Forwarded-Port)가 전달되지 않거나 무시되는 문제가 있었다.
• 그 결과, 모니터링과 디버깅 과정에서 실제 사용자의 접속 정보(IP/포트) 를 추적하기 어려웠다.

---

3. 결정 (Decision)

• 클라이언트 IP: X-Forwarded-For → X-Real-IP → request.client.host 순으로 확인해 기록.
• 포트 정보: X-Forwarded-Port → request.url.port → Host 헤더 → 기본 포트(443/80) 순으로 확인해 기록.

---

4. 대안 (Alternatives)

<<<<<<< Updated upstream

대안	장점	단점
기존 방식 유지 request.client.host와 Host만 사용	코드 단순, 별도 설정 불필요	프록시 환경에서 실제 사용자 IP·포트 추적 불가,"unknown" 로그 발생 가능
프록시 헤더 활용 (채택) X-Forwarded-For, X-Real-IP, X-Forwarded-Port 사용	외부망·내부망 모두에서 정확한 IP/포트 기록 가능	프록시 설정 누락 시 fallback 값(request.client.host, 443/80)으로만 기록됨

=======

대안	장점	단점
기존 방식 유지 request.client.host와 Host만 사용	코드 단순, 별도 설정 불필요	프록시 환경에서 실제 사용자 IP·포트 추적 불가,"unknown" 로그 발생 가능
프록시 헤더 활용 (채택) X-Forwarded-For, X-Real-IP, X-Forwarded-Port 사용	외부망·내부망 모두에서 정확한 IP/포트 기록 가능	프록시 설정 누락 시 fallback 값(request.client.host, 443/80)으로만 기록됨

Stashed changes

---

5. 결과 (Consequences)

• LLM Gateway의 로그에 실제 사용자 접속 정보(IP, 포트)가 일관되게 기록되어 모니터링과 디버깅 품질 개선.
• 프록시 설정(X-Forwarded-For, X-Real-IP, X-Forwarded-Port)이 누락되면 여전히 기본값(request.client.host, 443/80)으로만 기록될 수 있으므로, 인프라 설정 가이드와 함께 배포 필요