Hands-On with Langfuse: Tracing, Sessions, Evaluations, and LLM-as-a-Judge

🖼️ 인포그래픽

Hands-On with Langfuse: Tracing, Sessions, Evaluations, and LLM-as-a-Judge 내용을 설명하는 본문 이미지

🖼️ 4컷 인포그래픽

💡 한 줄 요약

이 글은 Langfuse를 로컬에 self-hosted로 설치한 뒤 OpenAI 호출 추적, 메타데이터, 세션·사용자 연결, 내장 평가기와 LLM-as-a-Judge 설정까지 직접 실습한 과정을 정리한다.

📌 핵심 요약

작성자는 LangfuseTest 작업 폴더를 만들고 VS Code에서 Langfuse GitHub 저장소를 클론한 뒤, 제공되는 Docker Compose 구성을 이용해 로컬 Langfuse 인스턴스를 실행했다.
Docker Compose 첫 실행에서는 PostgreSQL, Redis, ClickHouse, MinIO, Langfuse 웹·워커 서비스 이미지가 내려받아졌고, 컨테이너가 모두 실행된 뒤 http://localhost:3000에서 Langfuse에 접속할 수 있었다.
Langfuse에 처음 가입한 뒤 조직과 프로젝트를 생성하고, 애플리케이션이 Langfuse와 통신할 수 있도록 API 키를 발급해 .env 파일에 저장했다.
Python 환경에 Langfuse 클라이언트를 설치한 후 langfuse.openai의 OpenAI 클라이언트를 사용하자, 일반 OpenAI API 호출과 거의 같은 코드로 LLM 요청이 자동 추적되고 대시보드에서 트레이스, 비용, 점수, 사용량, 지연 시간 정보를 확인할 수 있었다.
이후 메타데이터, 세션 ID, 사용자 ID를 트레이스에 연결하는 방법과, Langfuse의 Evaluators 기능에서 LLM 연결을 설정하고 Correctness 템플릿을 선택해 LLM-as-a-Judge 방식으로 응답 품질을 평가하는 흐름을 실습했다.

🧩 주요 포인트

작성자는 LangfuseTest 작업 폴더를 만들고 VS Code에서 Langfuse GitHub 저장소를 클론한 뒤, 제공되는 Docker Compose 구성을 이용해 로컬 Langfuse 인스턴스를 실행했다.
Docker Compose 첫 실행에서는 PostgreSQL, Redis, ClickHouse, MinIO, Langfuse 웹·워커 서비스 이미지가 내려받아졌고, 컨테이너가 모두 실행된 뒤 http://localhost:3000에서 Langfuse에 접속할 수 있었다.
Langfuse에 처음 가입한 뒤 조직과 프로젝트를 생성하고, 애플리케이션이 Langfuse와 통신할 수 있도록 API 키를 발급해 .env 파일에 저장했다.
Python 환경에 Langfuse 클라이언트를 설치한 후 langfuse.openai의 OpenAI 클라이언트를 사용하자, 일반 OpenAI API 호출과 거의 같은 코드로 LLM 요청이 자동 추적되고 대시보드에서 트레이스, 비용, 점수, 사용량, 지연 시간 정보를 확인할 수 있었다.
이후 메타데이터, 세션 ID, 사용자 ID를 트레이스에 연결하는 방법과, Langfuse의 Evaluators 기능에서 LLM 연결을 설정하고 Correctness 템플릿을 선택해 LLM-as-a-Judge 방식으로 응답 품질을 평가하는 흐름을 실습했다.

🧠 상세 정리

1. 로컬 Langfuse 인스턴스 준비

글은 Langfuse를 직접 다뤄보기 위해 로컬 작업 환경을 만드는 과정에서 시작한다. 작성자는 LangfuseTest라는 워크스페이스 폴더를 만들고 VS Code에서 연 뒤, Langfuse 공식 GitHub 저장소를 클론했다. 저장소를 클론한 목적은 Langfuse가 제공하는 Docker Compose 설정을 그대로 활용해 로컬 인스턴스를 빠르게 띄우기 위해서였다. 클론이 끝나면 작업 폴더 안에 langfuse 디렉터리가 생성되고, 이후 실행에 필요한 구성 파일과 서비스 정의가 이 저장소 안에 준비된다.

2. Docker Compose로 서비스 실행

작성자는 Docker Desktop이 실행 중인지 확인한 뒤 클론한 Langfuse 저장소로 이동해 docker compose up 명령을 실행했다. 첫 실행 과정에서는 PostgreSQL, Redis, ClickHouse, MinIO, Langfuse web, Langfuse worker 등 필요한 컨테이너 이미지들이 내려받아졌다. 모든 컨테이너가 정상적으로 올라온 뒤 Langfuse는 로컬 주소 http://localhost:3000에서 접근 가능해졌다. 이 단계는 별도 서버를 준비하지 않고도 Langfuse의 관측성과 평가 기능을 실습할 수 있는 기본 기반을 마련하는 과정이다.

3. 회원가입, 조직, 프로젝트, API 키 설정

로컬 Langfuse 화면에 접속한 뒤 작성자는 처음 사용하는 사용자로 가입하고 로그인했다. Langfuse는 로그인 후 조직 생성을 요구하며, 사용자는 New Organization을 눌러 원하는 이름의 조직을 만들 수 있다. 이어 프로젝트를 생성하는데, 프로젝트는 트레이스, 평가, 프롬프트, 데이터셋 등 관측 관련 결과물을 담는 컨테이너 역할을 한다. 애플리케이션이 Langfuse와 통신하려면 Settings에서 새 API 키를 만들어야 하며, 작성자는 키를 생성한 뒤 .env 파일에 저장하는 방식으로 이후 Python 코드에서 사용할 준비를 마쳤다.

4. Langfuse Skill과 Python 클라이언트 설치

작성자는 Langfuse가 지원하는 코딩 에이전트용 Skill도 설치했다. npx skills add langfuse/skills --skill "langfuse" 명령을 실행하면 지원되는 코딩 에이전트 목록이 표시되고, 일부는 기본 선택되어 있었다. 작성자의 경우 Claude Code가 기본 선택에 포함되어 있지 않아 선택 목록에서 직접 골라 설치를 진행했다. 이후 가상환경 안에서 pip install langfuse 명령으로 Langfuse Python 클라이언트를 설치했고, pip list를 통해 Langfuse 패키지와 의존성이 설치된 것을 확인했다.

5. 첫 번째 OpenAI 호출 트레이스 캡처

SDK와 API 키 설정이 끝난 뒤 작성자는 간단한 OpenAI 호출 프로그램을 작성해 첫 트레이스를 생성했다. 코드는 일반 OpenAI API 호출과 거의 동일하지만, 클라이언트를 langfuse.openai에서 가져오는 점이 차이였다. gpt-4o-mini 모델에 소프트웨어 개발자에 관한 농담을 요청하는 메시지를 보내고 응답을 출력하는 예제가 사용되었다. 실행 후 Langfuse UI로 돌아가자 API 호출이 자동으로 추적되어 홈 대시보드에 Traces, Model Cost, Scores 같은 지표와 시각화가 나타났다.

6. 대시보드와 트레이스 상세 확인

작성자는 Langfuse의 Dashboard 화면에서 비용, 사용량, 지연 시간과 관련된 여러 대시보드를 확인했다. Cost 대시보드는 모델 사용에 따른 비용 관점의 정보를 보여주고, Usage 대시보드는 호출량과 사용 패턴을 파악하는 데 도움을 주며, Latency 대시보드는 응답 지연 시간의 관측에 초점을 둔다. Traces 화면에서는 각 행이 하나의 LLM 상호작용을 나타내며, 특정 트레이스를 클릭하면 해당 요청의 세부 내용을 드릴다운할 수 있다. 이를 통해 단순히 호출 성공 여부를 넘어서 어떤 요청이 언제 어떻게 처리되었는지 확인할 수 있다.

7. 메타데이터를 통한 트레이스 맥락 보강

작성자는 기본 트레이스만으로는 실제 애플리케이션 분석에 필요한 맥락이 부족할 수 있다고 설명한다. 이를 보완하기 위해 OpenAI 호출에 metadata를 붙이는 실험을 진행했다. 예시에서는 책 추천 요청에 대해 user_id를 amit, feature를 book-recommendation으로 전달했고, Langfuse의 해당 트레이스에서 이 값들이 표시되는 것을 확인했다. 이런 메타데이터는 이후 트레이스를 필터링하거나, 특정 기능·사용자·상황별 문제를 조사하고 분석하는 데 활용될 수 있다.

8. 세션과 사용자 ID로 관련 상호작용 묶기

개별 트레이스가 하나의 LLM 호출을 보여준다면, 세션은 서로 관련된 여러 상호작용을 묶어 보는 데 유용하다. 작성자는 observe와 propagate_attributes를 사용해 세션 ID와 사용자 ID를 전달하는 작은 프로그램을 작성했다. 예시에서는 amit-session-001이라는 세션 식별자와 AmitAnand라는 사용자 식별자를 연결해 OpenAI API 호출을 실행했다. 실행 후 Langfuse의 Sessions 탭에서는 해당 세션이 표시되었고, 세션을 클릭하면 그 세션에 연결된 트레이스들을 통합적으로 볼 수 있었다. Users 탭에서도 전달한 사용자 ID가 나타나며, 해당 사용자와 연결된 상호작용을 탐색할 수 있었다.

9. 내장 Evaluator와 LLM-as-a-Judge 실습

글의 후반부는 모델 응답이 실제로 좋은지 판단하는 문제로 이동한다. Langfuse는 LLM-as-a-Judge 방식을 지원하며, 이는 또 다른 언어 모델이 사전에 정의된 기준에 따라 생성된 응답의 품질을 평가하는 방식이다. 작성자는 Projects의 Evaluators 화면에서 Create Evaluator를 선택하고, 먼저 평가자로 사용할 LLM 연결을 설정했다. Add LLM Connection에서 평가에 사용할 모델을 선택해 저장한 뒤 Evaluators 화면으로 돌아왔고, 실험을 위해 Correctness 평가기 템플릿을 선택했다.

10. 평가 실행 옵션과 운영 관점의 의미

Evaluator 설정 과정에서 작성자는 새로 들어오는 관측값에 대해 평가를 자동 실행하는 옵션을 확인했다. Run on live incoming observation을 활성화하면 Langfuse가 새로 생성되는 트레이스를 도착하는 대로 평가할 수 있다. 또한 이미 캡처된 과거 관측값에 대해서도 필터를 적용해 평가를 실행할 수 있다고 설명한다. 글의 마지막 부분은 샘플링 슬라이더가 존재하며, 이 설정이 평가 대상이 되는 프로덕션 트레이스의 비율을 결정한다는 내용으로 이어진다. 즉 Langfuse의 평가는 단발성 실험뿐 아니라 새 요청과 기존 요청을 대상으로 한 지속적 품질 점검 흐름으로 확장될 수 있음을 보여준다.

🧾 핵심 주장 / 시사점

Langfuse의 OpenAI 통합은 기존 OpenAI 호출 코드와 큰 차이가 없도록 설계되어 있어, 클라이언트 import 변경만으로도 기본 트레이스 수집을 빠르게 시작할 수 있다는 점이 핵심이다.
트레이스만 보는 단계에서 메타데이터, 세션, 사용자 ID를 함께 기록하는 단계로 넘어가면, 단순 로그 확인이 아니라 기능별·사용자별·대화 흐름별 분석이 가능해진다.
Evaluator와 LLM-as-a-Judge 설정은 관측성 이후의 품질 관리 단계에 해당하며, 라이브 트레이스 자동 평가와 과거 트레이스 필터 평가를 함께 제공해 실험과 운영 모니터링을 연결한다.