feat(observability): Langfuse 전송 — 턴 마무리(사용자 trace)·게이트웨이(FabriX generation) 두 훅, SDK 없이 HTTP. deploy/langfuse 에 compose+env+반입 절차

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-22 13:44:12 +09:00
parent 95b169a7b9
commit 0321050053
13 changed files with 617 additions and 0 deletions
@@ -0,0 +1,41 @@
+# Langfuse 자체 호스팅 — -12 에 올리기
+
+LLM 호출 관측(누가·언제·어떤 모델·프롬프트·답·토큰·시간). 백엔드가 `LANGFUSE_HOST` 있으면 자동으로 쏨(`apps/gateway/langfuse.py`).
+공식 `docker-compose.yml` 그대로(2026-09-22 main). 컨테이너 6개, 밖으로 여는 건 웹 3000 하나.
+
+## 1. 이미지 반입 (인터넷 되는 PC)
+
+```bash
+cd 5_django_backend/deploy/langfuse
+docker compose pull
+docker save $(grep -oE 'image: \S+' docker-compose.yml | cut -d' ' -f2 | sed 's/\${POSTGRES_VERSION:-17}/17/') | gzip > langfuse-images.tar.gz
+ls -la langfuse-images.tar.gz     # 3~4GB. 메일 안 됨 — 인프라팀 반입 통로로
+```
+
+## 2. -12 에서 띄우기
+
+```bash
+docker load < langfuse-images.tar.gz
+cd /www/abap-ito/code-assistant/5_django_backend/deploy/langfuse
+cp .env.example .env && vi .env      # CHANGEME 전부 교체. NEXTAUTH_URL 은 사용자가 여는 주소
+docker compose up -d
+docker compose ps                    # 6개 healthy 까지 1~2분
+curl -s http://127.0.0.1:3000/api/public/health
+```
+
+## 3. 백엔드 연결
+
+`5_django_backend/.env` 에 (`.env` 의 INIT 키와 같은 값):
+```
+LANGFUSE_HOST=http://127.0.0.1:3000
+LANGFUSE_PUBLIC_KEY=pk-lf-…
+LANGFUSE_SECRET_KEY=sk-lf-…
+```
+`bash deploy.sh` 로 재기동 → 채팅 하나 보내고 Langfuse 웹(Traces)에 `chat`·`fabrix` trace 뜨면 끝.
+
+## 운영
+
+- 웹 UI 접속은 -12 의 3000 → 인프라팀이 외부 포트(8915 등) 매핑해줘야 고객사 PC 에서 열림
+- 중지 `docker compose down` (데이터 볼륨 남음) / 완전 삭제 `docker compose down -v`
+- 로그 `docker compose logs -f langfuse-web`
+- 백엔드는 Langfuse 죽어 있어도 멀쩡(전송 실패는 warning 로그만)