langfuse/langfuse는 LLM(대규모 언어 모델)을 사용한 애플리케이션을 개발·모니터링·평가·디버깅하기 위한 오픈소스 플랫폼입니다. 2023년에 공개되었으며, GitHub 스타 수는 집필 시점 기준 약 28,400개입니다. Y Combinator의 2023년 겨울 배치(W23) 출신 프로젝트이기도 합니다. 본체는 TypeScript로 제작되었으며, 라이선스는 MIT입니다.

LLM 앱은 만드는 것만이라면 의외로 쉽게 동작합니다. 하지만 프로덕션(production)에서 운영을 시작하면, "왜 이런 답변이 나왔는가", "어디에서 시간이 걸리고 있는가", "품질이 올라가고 있는가 내려가고 있는가"가 보이지 않아 곤란해지는 벽에 부딪힙니다. 프로토타입에서는 기분 좋게 동작했는데, 실제 사용자가 사용하기 시작하자마자 "가끔 이상한 대답을 한다", "왠지 느리다"와 같은 목소리가 올라옵니다. 하지만 나온 답변만 봐서는 원인을 알 수 없습니다. 이 "내부가 보이지 않는" 답답함은 LLM 앱을 운영해 본 사람이라면 누구나 겪어봤을 법한 일입니다.

Langfuse는 이러한 **가관측성 (observability)**을 중심으로 LLM 앱의 운영을 지원하려는 도구입니다. 이 기사에서는 LLM 앱을 개발·운영하는 엔지니어를 대상으로, Langfuse가 무엇을 해결하는지, 어떤 기능이 있는지, 어떻게 시작하는지, 그리고 팀에서 어떻게 운영에 적용해 나갈지까지 정리해 보겠습니다.

이 기사에서 알 수 있는 내용:

• 🤔 LLM 앱의 운영이 일반적인 앱 운영과 무엇이 다른가 (읽기 전 전제 조건)
• 🔍 observability (가관측성)가 LLM 앱에서 왜 중요한가
• 🧰 6가지 주요 기능 (Tracing / 프롬프트 관리 / 평가 / 데이터셋 / 플레이그라운드 / API)
• 🔌 20개 이상의 통합 (OpenAI, Langchain, LiteLLM, OpenTelemetry 등)
• 🗺️ 평가 설계·Dataset화·Prompt Management의 현실적인 운영
• 🚀 클라우드와 셀프 호스팅(self-host) 중 선택하는 방법
• 🐍 SDK를 통한 시작 방법과 첫 30일간의 진행 방식
• 👥 팀 도입 시 빠지기 쉬운 함정

조금 길지만, "우리 운영에 도입할 수 있을까"를 판단할 수 있는 재료들을 가득 담았습니다. 궁금한 제목부터 읽으셔도 괜찮습니다.

Langfuse 이야기를 하기 전에, "LLM 앱의 운영은 일반적인 앱 운영과 무엇이 다른가"를 짚고 넘어가겠습니다.

일반적인 앱은 기본적으로 동일한 입력에는 동일한 출력을 반환합니다. 버그가 있다면 동일한 절차로 재현할 수 있습니다. 따라서 로그를 보면 대부분 원인에 도달할 수 있습니다.

하지만 LLM 앱은 다릅니다. 동일한 입력이라도 매번 조금씩 다른 출력이 될 수 있습니다. 게다가 내부에서는 검색·프롬프트 구성·모델 호출·도구 사용 등이 여러 단계로 겹쳐 있어, 어디에서 품질이 떨어졌는지 보기가 어렵습니다. "왠지 최근 답변이 안 좋은 것 같다"라는 느낌을 감각이 아닌 데이터로 추적할 수 있게 만드는 것—이것이 LLM 앱 운영의 어려움이며, Langfuse가 목표로 하는 영역입니다.

이 그림은 일반적인 앱과 LLM 앱의 "추적 용이성" 차이를 보여줍니다. 여기서 주목해야 할 점은 LLM 앱은 출력이 흔들리는 데다 처리가 다단계이므로 전용 시각화가 필요하다는 점입니다. 일반적인 앱을 위한 모니터링만으로는 LLM 특유의 "왜 이런 답변이 나왔는가"에 도달하기 어렵습니다.

LLM 앱은 내부에서 다양한 일이 일어납니다. 사용자의 입력을 받고, 관련 정보를 검색하고, 프롬프트를 구성하고, 모델을 호출하며, 때로는 에이전트가 여러 도구를 사용합니다. 그런데 나온 답변만 보고 있어서는 "도중에 무엇이 일어났는지"를 알 수 없습니다. 좋은 답변이라면 몰라도, 이상한 답변이 돌아왔을 때 어디가 원인인지 추적할 수 없다는 것은 매우 힘든 일입니다.

여기서 등장하는 개념이 **observability (가관측성)**입니다. 이는 "시스템 내부에서 일어나고 있는 일을 외부에서 관찰할 수 있는 상태로 두는 것"을 의미합니다. 그 핵심이 Tracing (트레이싱), 즉 일련의 처리 흐름을 기록하여 나중에 추적할 수 있도록 하는 것입니다.

이 그림은 가관측성의 유무에 따라 "문제가 생겼을 때 추적할 수 있는지 여부"가 달라짐을 보여줍니다. 여기서 주목해야 할 점은 Langfuse가 처리 단계 하나하나를 기록하여, 나중에 "여기서 이렇게 되었다"라고 거슬러 올라갈 수 있게 한다는 점입니다. 이것이 있으면 이상한 답변을 만났을 때 원인이 있는 지점까지 내려갈 수 있습니다.

💡「트레이스 (Trace)」는 하나의 요청이 처리되는 동안 발생한 일을 시계열로 연결한 기록입니다. 무엇을 검색에 사용했는지, 어떤 프롬프트 (Prompt)를 조합했는지, 모델이 무엇을 반환했는지 등을 일련의 흐름으로 남깁니다. 이것이 있으면 나중에 "3번째 단계에서 관련 없는 정보를 가져왔다"와 같이 문제의 위치를 특정할 수 있습니다.

Langfuse는 가관측성 (Observability)을 기점으로, LLM 앱 운영에 필요한 기능들을 두루 갖추고 있습니다. 주요 6가지 기능과 API를 살펴보겠습니다.

이 그림은 Langfuse가 제공하는 기능군을 조망한 것입니다. 각각을 간단히 설명합니다.

LLM Observability (LLM 가관측성/트레이싱): 앱에 트레이싱 (Tracing)을 통합하여 LLM 호출, 검색, 임베딩 (Embedding), 에이전트 (Agent)의 행동 등을 추적합니다. 복잡한 로그나 사용자 세션 (Session)을 검사하고 디버깅할 수 있습니다. Langfuse의 핵심 기능입니다.

Prompt Management (프롬프트 관리): 프롬프트를 일원화하여 관리하고 버전 관리 (Version Control)를 수행합니다. 팀 단위로 협력하며 개선할 수 있으며, 서버 측 및 클라이언트 측 캐시 (Cache)를 통해 운영에 불필요한 지연을 더하지 않고 반복 (Iteration)할 수 있다고 합니다.

Evaluations (평가): 품질을 어떻게 측정할 것인가에 대한 부분입니다. LLM-as-a-judge (LLM 스스로가 다른 LLM의 출력을 채점하게 하는 기법), 코드를 통한 평가, 사용자 피드백 수집, 수동 라벨링 (Manual Labeling), 커스텀 평가 파이프라인 (Custom Evaluation Pipeline)에 대응합니다.

Datasets (데이터셋): 테스트 세트나 벤치마크 (Benchmark)를 만드는 기능입니다. 배포 전 테스트나 구조화된 실험에 사용할 수 있습니다.

LLM Playground (LLM 플레이그라운드): 프롬프트나 모델 설정을 시도해 보는 장소입니다. 트레이싱을 통해 나쁜 결과를 발견하면, 그곳에서 직접 플레이그라운드로 이동하여 개선할 수 있는 동선으로 설계되어 있습니다.

Metrics (메트릭스): 퍼포먼스 (Performance) 측정입니다.

그리고 API: OpenAPI 사양, Postman 컬렉션, Python / JS / TS 타입 지정 SDK가 제공됩니다.

💡「LLM-as-a-judge」는 사람이 모든 출력을 채점하는 대신, LLM에게 채점 역할을 맡기는 기법입니다. 확장성(Scalability)이 좋은 반면, judge 자체의 정확도도 살펴볼 필요가 있습니다. Langfuse는 이를 포함한 여러 가지 평가 방법을 통합하여 다룰 수 있습니다.

여기서 중요한 점은, 이 6가지가 독립된 기능의 모음이 아니라 하나의 개선 루프 (Improvement Loop) 로 연결되어 있다는 것입니다.

이 그림은 6가지 기능이 「발견 → 개선 → 기록 → 테스트화 → 평가」라는 순환을 만드는 모습을 보여줍니다. 여기서 읽어내야 할 점은, Langfuse가 「관측하고 끝나는 것」이 아니라, 관측으로부터 개선과 평가까지 한 바퀴 돌 수 있도록 설계되었다는 점입니다. 트레이스로 문제를 발견하고, Playground에서 수정하고, 그것을 Dataset에 추가하여 이후의 테스트로 삼고, Evaluations로 좋아졌는지 측정합니다. 이 한 바퀴를 계속 돌리는 것이 LLM 앱의 품질을 꾸준히 높여가는 길로 이어집니다.

Langfuse를 도입할 때 현실적으로 중요한 것은 자신이 사용 중인 프레임워크 (Framework)나 SDK와 연결되는가 입니다. Langfuse는 20개 이상의 주요 패키지와 통합할 수 있다고 알려져 있습니다. 대표적인 것들을 나열합니다.

💡OpenTelemetry는 시스템의 가관측성 데이터 (트레이스나 메트릭스)를 다루기 위한 업계 표준 규격입니다. 이에 대응하면 Langfuse 전용의 커스텀 구현에 얽매이지 않고, 기존의 가관측성 체계와 연속적으로 사용할 수 있습니다.

「지금 사용 중인 스택 (Stack)에 그대로 끼워 넣을 수 있다」는 점이 많은 경우가 도입 장벽을 낮추는 큰 포인트입니다. 예를 들어 OpenAI의 SDK를 그대로 교체하기만 하면 되거나, Langchain이라면 콜백 (Callback)을 하나 추가하기만 하면 되는 것처럼, 앱의 구조를 크게 바꾸지 않고도 측정을 시작할 수 있다는 것이 현실적인 이점입니다.

실제로 README에는 Langflow, Open WebUI, Lobe Chat, LlamaIndex, Firecrawl, LiteLLM과 같은 유명한 OSS 프로젝트들이 Langfuse를 채택하고 있다고 명시되어 있습니다.

가시성(Observability)은 '시각화'를 의미하지만, Langfuse의 가치는 거기서 한 걸음 더 나아가 '품질을 측정하고 개선하는 것'에 있습니다. 이 부분은 도입 후 운영 단계에서 큰 효과를 발휘하므로 조금 자세히 살펴보겠습니다.

LLM 앱의 품질을 측정하는 것은 일반적인 테스트보다 어렵습니다. '정답이 하나로 정해지지 않기' 때문입니다. 예를 들어 요약 태스크라면, 좋은 요약문은 여러 개가 존재할 수 있습니다. Langfuse는 이러한 어려움에 대해 여러 가지 접근 방식으로 대응합니다.

LLM-as-a-judge: LLM이 직접 채점하게 합니다. 확장성(Scalability)은 높지만, judge 자체의 정확도도 확인이 필요합니다.
코드를 통한 평가: '특정 키워드를 포함하는가'와 같이 기계적으로 판정할 수 있는 항목입니다.
사용자 피드백: 실제 사용자의 '좋음/나쁨' 반응을 수집합니다.
수동 라벨링 (Manual Labeling): 사람이 직접 눈으로 보고 채점합니다. 소수라도 기준을 만드는 데 유효합니다.

실무에서는 이것들을 조합하는 것이 현실적입니다. 먼저 수동 라벨링을 통해 '무엇을 좋다고 할 것인가'에 대한 기준을 만들고, 이를 LLM-as-a-judge에 적용하여 확장시키며, 사용자 피드백을 통해 실제 체감 성능을 확인하는 흐름입니다.

평가를 단 한 번으로 끝내지 않고 지속적으로 순환시키기 위해서는 Datasets가 효과적입니다. 트레이스(Trace)를 통해 발견한 '나쁜 결과'를 Dataset에 추가해 나가면, 그것이 이후의 회귀 테스트(Regression Test, 이전에는 고쳤는데 다시 나빠지지 않았는지 확인하는 테스트)가 됩니다.

이 그림은 운영 환경에서 발견한 문제를 Dataset에 포함시켜, 배포 전 테스트로 재사용하는 흐름을 보여줍니다. 여기서 주목해야 할 점은, '운영 중 발생한 실패'를 '다음에는 방지하기 위한 테스트'로 바꿀 수 있다는 점입니다. 이를 지속하면 테스트 세트는 자신들의 앱의 약점을 반영한 실용적인 형태로 성장하게 됩니다.

프롬프트는 코드만큼이나 품질을 좌우합니다. Langfuse의 프롬프트 관리(Prompt Management)는 프롬프트를 버전 관리 (Version Control) 할 수 있으므로, '이 변경으로 인해 좋아졌는지 혹은 나빠졌는지'를 나중에 추적할 수 있습니다. 또한 캐시(Cache)가 적용되므로, 운영에 불필요한 지연(Latency)을 추가하지 않고도 반복적인 개선이 가능하다고 합니다.

운영의 핵심은 프롬프트를 '코드 외부'에서 관리하는 것입니다. 프롬프트를 코드에 직접 작성(Hard-coding)하면 변경할 때마다 배포가 필요합니다. Langfuse로 관리하면 프롬프트 개선과 앱 배포를 분리할 수 있어 개선 사이클이 빨라집니다.

Langfuse는 몇 가지 시작 방법을 제공합니다. 로컬에서 테스트할 것인지, 운영 환경에서 사용할 것인지에 따라 선택합니다.

이 그림은 이용 시나리오별 배포 선택지를 보여줍니다.

Langfuse Cloud: 공식에서 운영하는 매니지드(Managed) 버전입니다. 무료 티어가 있으며 신용카드는 필요하지 않습니다. 우선 테스트해 보기에 가장 빠른 방법입니다.
로컬 (Docker Compose): git clone 후 docker compose up을 하는 것만으로 약 5분 안에 기동할 수 있다고 합니다. 로컬 검증용으로 적합합니다.
Kubernetes (Helm): 운영 환경을 위한 권장 구성입니다.
Terraform: AWS / Azure / GCP용 템플릿이 준비되어 있습니다.

셀프 호스팅(Self-hosting)의 경우, Langfuse는 내부적으로 ClickHouse(대량의 데이터를 고속으로 집계하는 데 특화된 데이터베이스)를 사용합니다.

선택지가 많아 고민된다면 다음 판단 기준을 참고하세요.

**"우선 Cloud의 무료 티어로 사용해 보고, 데이터 취급 요건이나 확장성 문제로 셀프 호스팅이 필요해지면 이전한다"**는 순서가 현실적입니다. 처음부터 셀프 호스팅으로 전체 구성을 구축하려고 하면 ClickHouse를 포함한 인프라 운영이 부담이 되기 쉽습니다. Cloud로 가치를 먼저 확인한 후 본격적인 운영 형태를 고민하는 것이 합리적입니다.

⚠️ 라이선스는 'MIT'입니다. Enterprise Edition에 해당하는 ee 폴더 부분은 별도의 라이선스이므로, 셀프 호스팅으로 사용하는 범위가 어디까지인지 확인해 두는 것이 안전합니다.

Python을 예로 들어, 최소한의 시작 방법을 살펴보겠습니다. OpenAI와 함께 사용하는 경우입니다.

pip install langfuse openai

사용법의 핵심은 @observe() 데코레이터 (decorator) 입니다 (이하는 개념을 보여주기 위한 예시이며, 실제 API는 버전에 따라 달라질 수 있습니다). 함수에 이를 붙이면 해당 함수의 실행이 트레이스 (trace)로 기록된다는 이미지입니다. OpenAI 통합을 사용하면 모델의 파라미터 (parameter) 등도 자동으로 가져옵니다. 실행 결과는 Langfuse의 대시보드 (dashboard)에 표시되어 나중에 추적할 수 있는 상태가 됩니다.

인증 및 엔드포인트 (endpoint)는 환경 변수로 지정합니다.

LANGFUSE_SECRET_KEY

— 시크릿 키 (secret key) -
LANGFUSE_PUBLIC_KEY

— 퍼블릭 키 (public key) -
LANGFUSE_BASE_URL

— 접속 대상 (Cloud인지, 직접 셀프 호스팅한 곳인지)

"먼저 Cloud에 등록하고, SDK를 설치하여 @observe()를 붙인다"는 것만으로 트레이스가 대시보드로 흐르기 시작하는 간편함이 있습니다. 정확한 작성법은 달라질 수 있으므로, 구현 시에는 공식 문서의 최신 샘플을 확인하십시오.

💡 텔레메트리 (telemetry, 이용 상황 데이터)가 수집되는 설정으로 되어 있지만, 가공되지 않은 트레이스, 프롬프트, 스코어 (score)는 포함되지 않는다고 합니다. 신경 쓰인다면 TELEMETRY_ENABLED=false로 무효화할 수 있습니다.

설치만 하고 끝내지 않도록, 첫 1개월의 가이드라인을 정해 두겠습니다. 어디까지나 하나의 예시입니다.

이 표의 포인트는 "관측 → 개선 → 테스트화 → 평가"를 1개월 동안 한 바퀴 돌려보는 것입니다. 우선 보이게 만들고, 수정해 보고, 그것을 테스트로 바꾸고, 품질을 측정합니다. 이 한 바퀴를 경험해 두면, Langfuse를 단순한 로그 뷰어 (log viewer)가 아니라 "개선 루프 (improvement loop)"로 사용할 수 있게 됩니다.

개인적으로 테스트할 때는 간단한 Langfuse이지만, 팀 단위로 운영에 올릴 때는 몇 가지 걸림돌이 될 수 있는 포인트가 있습니다. 미리 알고 있으면 회피하기 쉬우므로 공유해 드립니다.

첫 번째는, "설치만 하고" 멈춰버리기 쉽다는 점입니다. 트레이싱 (tracing)을 심는 것까지는 했지만, 아무도 대시보드를 보지 않는 상태가 되기 쉽습니다. 대책으로는 "이상한 답변 보고가 들어오면 먼저 트레이스를 확인한다"라는 운영 규칙을 처음에 정해두는 것이 효과적입니다.

두 번째는, 평가 기준 만들기가 뒤로 밀리는 것입니다. "품질을 측정하자"라고 말하면서도 무엇을 좋다고 할지가 모호한 채로 LLM-as-a-judge를 돌리면, judge의 채점을 신뢰할 수 없습니다. 적은 수라도 좋으니, 처음에 수동 라벨링 (manual labeling)으로 기준을 만드는 것이 멀리 돌아가는 것 같지만 지름길입니다.

세 번째는, 프롬프트 관리 장소가 분산되는 것입니다. 코드에 직접 쓰는 사람, 스프레드시트로 관리하는 사람, Langfuse로 관리하는 사람이 혼재하면 어떤 것이 최신인지 알 수 없게 됩니다. 프롬프트 관리 (Prompt Management)로 모으기로 결정했다면, 팀 전체가 통일하는 것이 중요합니다.

여기까지를 바탕으로 적합한 경우와 그렇지 않은 경우를 정리합니다.

반대로, 아직 시제품 단계이고 프로덕션 운영을 하지 않고 있다면 가시성 (observability) 기능이 오버스펙 (over-spec)으로 느껴질 수도 있습니다. 그렇지만 Cloud의 무료 티어 (free tier)로 간편하게 시작할 수 있으므로, "프로덕션에 내보내기 전에 한 번 트레이스를 확인해 본다" 정도의 가벼운 마음으로 접해 보는 것이 좋습니다. "관측이 필요할 정도로 복잡한 일을 아직 하고 있지 않은" 단계라면, 무리하게 모든 기능을 사용하지 않고 트레이싱부터 시작하는 것도 충분히 괜찮습니다.

Langfuse를 한마디로 요약하면, **"LLM 앱 내부에서 어떤 일이 일어나고 있는지 추적할 수 있게 하며, 프롬프트 개선 및 품질 평가까지 지원하는 오픈소스 운영 기반"**입니다.

개인적으로 가장 가치를 느끼는 점은 "왜 이런 답변이 나왔는가"를 나중에 추적할 수 있다는 점 하나입니다. LLM 앱은 실행하는 것 자체는 쉬워졌습니다. 하지만 프로덕션에서 신뢰하며 계속 사용하기 위해서는 이상한 동작의 원인을 추적할 수 있는 상태가 반드시 필요합니다. Langfuse는 그 부분에 대해 트레이싱을 기점으로 한 해답을 제시하고 있습니다.

그리고 단순히 관측(Observability)에서 끝나는 것이 아니라, Playground에서의 개선, Dataset을 통한 테스트화, 그리고 Evaluations를 통한 품질 측정까지 하나의 사이클을 완성할 수 있도록 설계되어 있다는 점이 장기적으로 사용할 때의 강점입니다. 게다가 OpenAI, Langchain, LiteLLM, OpenTelemetry와 같이 널리 사용되는 도구들에 바로 삽입할 수 있으므로, 현재의 스택을 크게 바꾸지 않고도 시작할 수 있습니다. 도입 장벽이 낮다는 것은 운영 도구로서 매우 중요한 특성입니다.

LLM 애플리케이션을 운영하면서 "내부가 보이지 않아 어려움을 겪고 있다면", 우선 Cloud 무료 티어에 등록하여 @observe()를 하나 추가하는 것부터 시도해 보세요. 첫 번째 사이클(관측 → 개선 → 테스트화 → 평가)을 경험해 본다면, Langfuse가 단순한 로그 뷰어(Log Viewer)가 아니라 품질을 꾸준히 높여가기 위한 "개선의 루프(Improvement Loop)"라는 것을 실감할 수 있을 것입니다.