Claude Code 세션 옵저버빌리티를 직접 만들어봤음 – Langfuse 셀프호스팅으로

왜 필요했나

• Principal AI Architect가 Claude Code를 메인 개발 도구로 쓰면서, 하루 20~50턴의 대화를 여러 프로젝트에서 돌리고 있었음
• 문제는 터미널을 닫는 순간 디버깅 세션, 아키텍처 논의, 프롬프트 노하우 등 모든 맥락이 사라진다는 것
• "어떤 프롬프트가 좋은 결과를 내는지", "Claude가 도구를 어떻게 활용하는지", "생산적인 세션의 구조는 뭔지" 같은 질문에 답할 수 없었음
• 기업 AI 시스템에 옵저버빌리티 구축해주는 게 본업인데, 정작 본인 도구에는 없다는 아이러니를 깨달음

첫 시도: 마크다운 로그의 한계

• 처음엔 log-prompt.py 훅으로 프롬프트를 마크다운 파일에 append하는 방식을 썼음
• 2주 만에 7가지 문제가 드러남:
  1. 파일이 무한 성장 (수천 줄)
  2. 긴 프롬프트가 500자로 잘림 — 정작 중요한 상세 프롬프트가 손실됨
  3. Claude의 응답은 아예 기록 안 됨 (대화의 절반만 저장)
  4. 마크다운이라 쿼리 불가
  5. 세션 컨텍스트 없음 — 9턴짜리 디버깅이 9개의 단절된 항목으로 보임
  6. "[outcome pending]"이 영원히 pending으로 남음
  7. 프로젝트 간 패턴 분석 불가

"이건 그냥 LLM 옵저버빌리티잖아"

• 필요한 게 결국 트레이스, 스팬, 세션 그룹핑, 쿼리 가능한 저장소, 크로스 프로젝트 집계라는 걸 깨달음
• Langfuse를 선택한 이유: 셀프호스팅 가능(데이터가 내 머신에 유지), 트레이스/스팬/세션/제너레이션 데이터 모델 내장, 웹 UI 제공, API 쿼리 가능, 오픈소스
• 마침 Langfuse가 ClickHouse와 합류한 타이밍이기도 했음

아키텍처와 셋업

• Docker Compose로 6개 서비스 구동: Langfuse, PostgreSQL, ClickHouse, Redis, MinIO, 웹 UI(localhost:3050)
• 메모리 사용량 약 46GB, 디스크 이미지 25GB + 데이터
• 셋업은 딱 5개 명령어: git clone → generate-env.sh → docker compose up -d → health check → install-hook.sh
• generate-env.sh가 PostgreSQL, ClickHouse, Redis, MinIO, Langfuse 암호화 키 등 모든 크레덴셜을 자동 생성해줌
• 템플릿 레포 공개됨: github.com/doneyli/claude-code-langfuse-template

훅 동작 원리

• Claude Code의 Stop 훅으로 동작 — 모든 어시스턴트 응답 후 자동 실행됨
• ~/.claude/projects/<project>/ 아래 .jsonl 트랜스크립트에서 최신 파일을 찾아 파싱
• 증분 처리: langfuse_state.json에 마지막 읽은 라인을 기록해서, 매번 새 메시지만 처리. 수백 턴 후에도 1초 이내로 실행됨
• 메시지를 턴 단위로 그룹핑: 사용자 프롬프트 → 어시스턴트 응답 → 도구 호출을 하나의 트레이스로 묶음
• 각 트레이스에 자식 스팬으로 Read, Write, Edit, Bash, Grep, Glob 등 도구 호출이 전부 기록됨
• 모든 예외는 sys.exit(0) 처리 — 훅이 절대로 Claude Code 세션을 블로킹하지 않음

오프라인 큐: 데이터 유실 방지

• Langfuse가 다운됐을 때 트레이스가 유실되는 문제를 해결하기 위해 로컬 큐 추가
• 매번 2초 타임아웃 소켓 체크로 Langfuse 상태 확인 (HTTP가 아니라 raw socket — 속도 때문)
• 다운이면 ~/.claude/state/pending_traces.jsonl에 JSONL로 저장, 각 항목에 queued_at 타임스탬프 포함
• 다음에 Langfuse가 살아나면 현재 턴 처리 전에 큐를 자동으로 drain
• 보수적 접근: 큐 전송 중 하나라도 실패하면 중단하고 나머지는 보존. 데이터 손실 없음
• 별도 데몬 대신 "다음 Claude Code 사용 시 자동 drain" 방식을 택함 — 단순함이 답이라는 판단

설정 모델과 활용

• 기본은 글로벌 활성화 — 모든 프로젝트가 자동 트레이싱됨
• 특정 프로젝트에서 끄려면 .claude/settings.local.json에 TRACE_TO_LANGFUSE: false 추가하면 됨
• 반대로 opt-in 모델도 가능: 글로벌 env 제거 후 프로젝트별로 추가

데이터로 할 수 있는 것들

• 프로젝트별 필터링: 모든 트레이스에 프로젝트명 태그가 붙어서 코드베이스별 분석 가능
• 도구 사용 패턴 분석: Claude가 문제 해결 시 파일 읽기, 검색, 편집을 어떤 순서로 하는지 파악
• 베스트 프롬프트 검색: 입력 텍스트로 트레이스 검색해서 좋은 결과 낸 프롬프트 패턴 재활용
• 세션 리플레이: 멀티턴 디버깅 세션을 시간순으로 전체 재생 가능
• 다음 단계로 Langfuse API를 쿼리해서 "이번 주 가장 복잡한 디버깅 세션", "최고의 아키텍처 프롬프트" 같은 패턴 분석을 자동화할 계획