repository link https://github.com/Dan1618/langfuse-observability

서론 (Introduction)

이 포스트에서는 에이전트 애플리케이션 (agent application)의 관측성 (observability)을 지원하기 위해 Langfuse를 로컬에 설치하는 방법을 보여드리겠습니다. 이를 통해 우리는 사용된 프롬프트 (prompt), 에이전트의 답변, 또는 토큰 사용량 (token usage)과 같은 에이전트의 내부 속성들을 관찰할 수 있습니다.
저는 이 기사 https://dev.to/dan1618/building-ai-agent-with-langgraph-and-nestjs-4d86에서 사용된 기존 애플리케이션을 사용할 것입니다.

왜 에이전트 애플리케이션의 관측성 (observability)이 중요한가?

관측성 (Observability)이란 소프트웨어 동작의 "어떻게"와 "왜"에 대해 깊은 가시성을 갖는 것을 의미하며, 이는 AI의 부상과 함께 급격히 진화하고 있는 요구사항입니다. 전통적인 애플리케이션 성능 모니터링 (APM) 도구들은 결정론적 (deterministic) 시스템을 위해 구축되었습니다: 사용자가 버튼을 클릭하면, 미리 정의된 API가 호출되고, 데이터베이스가 쿼리되며, 응답이 반환됩니다. 만약 AI 에이전트에 전통적인 APM 도구를 사용하려고 한다면, LLM 제공업체로 HTTP 요청이 전송되었고 4초가 소요되었다는 사실만 알 수 있을 것입니다. 모델이 무엇을 생각하고 있었는지는 알려주지 않습니다. LLM을 사용하는 것은 비용 (Cost) 및 토큰 관리 (Token Management), 추론 루프 (Reasoning Loops, 우리는 서로 다른 에이전트를 생성하는 에이전트 및 기타 에이전트 특유의 동작을 고려해야 합니다), 그리고 응답 품질 추적 (Tracking Response Quality, Evals)과 같은 서로 다른 요소들을 측정할 것을 요구합니다.

왜 Langfuse인가?

Langfuse는 AI 지표를 기존의 APM 대시보드에 억지로 끼워 맞추려 하기보다, LLM의 확률론적 (probabilistic) 특성을 위해 특별히 구축되었기 때문에 필수적인 오픈 소스 AI 엔지니어링 플랫폼으로 떠올랐습니다.

• 목적에 맞게 구축된 추적(Purpose-Built Tracing): LLM 개념을 본질적으로 이해합니다. 세션, 개별 교환, LLM 호출, 외부 도구 사용 등 전체 실행 트리(execution tree)를 추적하여 에이전트의 정확한 의사 결정 경로를 시각적으로 검사할 수 있습니다.
• OpenTelemetry (OTel) 네이티브: AutoGen, Pydantic AI 또는 Amazon Bedrock AgentCore와 같은 최신 에이전트 프레임워크는 OpenTelemetry를 통해 추적(traces)을 방출합니다. Langfuse는 이러한 표준 OTel 추적을 원활하게 수집하여 자체 생성형 AI 데이터 모델에 매핑합니다.
• 프롬프트 관리(Prompt Management): Langfuse를 사용하면 프롬프트를 코드베이스에서 분리할 수 있습니다. 애플리케이션을 재배포할 필요 없이 플랫폼 내에서 프롬프트를 테스트, 버전 관리 및 롤백 할 수 있습니다.
• 내장 평가 기능(Built-in Evaluations): 프로덕션 데이터에 대해 지속적으로 '평가(evals)'를 실행할 수 있게 합니다. 지연 시간(latency)과 비용과 함께 품질 지표(충실도(faithfulness), 정확도(accuracy))를 추적하고, 에이전트의 성능이 저하되면 경고를 발생시킬 수 있습니다.

Langfuse 기능

여기에서 YouTube 시각 개요를 확인하세요: https://www.youtube.com/watch?v=2E8iTvGo9Hs

Langfuse 대시보드 내부에서 추적하고 상호 작용할 수 있는 핵심 기능 및 지표는 여러 주요 영역에 걸쳐 구성되어 있습니다:

1. 핵심 관측성 및 심층 추적 (Core Observability & In-Depth Tracing)

추적(Tracing)은 이 플랫폼의 기반입니다. 대시보드는 LLM 실행 과정에서 내부적으로 정확히 어떤 일이 발생하는지 시각적으로 매핑할 수 있게 합니다:

• 계층적 추적 뷰 (Hierarchical Trace Views): 요청의 전체 실행 여정을 볼 수 있습니다. 다단계 에이전트 워크플로우를 타임라인 또는 시각적 그래프로 분해하여 모든 도구 호출, 검색 단계(RAG), LLM 호출을 보여줍니다.
• 세션 추적 (Session Tracking): 개별 추적들을 '세션(Sessions)'으로 그룹화하여 시간이 지남에 따라 발생하는 다중 턴 사용자 대화를 추적하고 디버깅할 수 있습니다.
• 심층 필터링 (Deep Filtering): 사용자 ID, 특정 모델, 릴리스/버전 또는 사용자 지정 메타데이터 태그별로 실행 데이터를 빠르게 분리(slice)할 수 있습니다.

2. 실시간 성능 및 상태 지표 (Live Performance & Health Metrics)

홈 대시보드는 시스템 안정성을 모니터링하기 위해 기술적 지표를 기본적으로 집계합니다:

• 지연 시간 모니터링 (Latency Monitoring): 전체 응답 시간과 첫 번째 토큰 생성 시간 (Time-to-First-Token, TTFT) 분포를 검사하여 에이전트의 병목 구간이나 느린 단계를 찾아냅니다.
• 스트리밍 속도 (Streaming Speed): 실시간 사용자 경험을 최적화하기 위해 초당 토큰 수를 추적합니다.
• 에러율 (Error Rates): 실패한 LLM 호출, 타임아웃 에러 또는 API 오류를 자동으로 표시합니다.

3. 비용 및 토큰 추적 (Cost & Token Tracking)

LLM 비용은 빠르게 통제 불능 상태가 될 수 있습니다. 대시보드에는 강력한 비용 관리 스위트가 포함되어 있습니다:

• 토큰 세부 내역 (Token Breakdowns): 다양한 모델 유형(예: GPT-4, Claude, Llama)별로 집계된 정확한 토큰 소비량(입력 토큰 vs 출력 토큰)을 추적합니다.
• 비용 귀속 (Cost Attribution): 지출 트렌드를 계산하고 모델 제공업체별 또는 개별 사용자 ID별로 비용 세부 내역을 확인하여, 누가 또는 무엇이 API 비용을 발생시키는지 파악할 수 있습니다.

4. 평가 및 품질 분석 (Evaluation & Quality Analytics)

대시보드는 귀하의 애플리케이션이 실제로 양질의 안전한 답변을 출력하고 있는지 이해하도록 도와줍니다:

• 다중 방식 점수 추적 (Multi-Method Score Tracking): 사용자 피드백(좋아요/싫어요), 수동 휴먼 어노테이션(human annotations), 또는 자동화된 "LLM-as-a-judge" 평가기(환각(hallucinations), 정확성, 독성(toxicity) 등을 검사)로부터 수집된 품질 점수를 시각화합니다.
• 어노테이션 큐 (Annotation Queues): 팀이 프로덕션 트레이스(production traces)를 체계적으로 검토하고, 라벨을 적용하며, 향후 테스트를 위한 "골든 데이터셋 (golden datasets)"을 구축할 수 있는 공간을 제공합니다.

5. 커스텀 대시보드 및 고급 보고 (Custom Dashboards & Advanced Reporting)

Langfuse는 관련 없는 차트로 인해 혼란을 겪지 않도록 완전히 커스터마이징 가능한 대시보드 빌더를 포함하고 있습니다:

• Widget Builder (위젯 빌더): 맞춤형 뷰를 구축하기 위해 다양한 차트(히스토그램 또는 선 그래프 등)를 생성, 이동 및 크기 조절할 수 있습니다.
• Pivot Tables (피벗 테이블): 내장된 피벗 테이블 위젯을 통해 다차원 데이터 분석이 가능합니다. 예를 들어, 다양한 애플리케이션 기능에 걸쳐 품질 점수(quality scores)가 모델 비용(model costs)과 어떻게 대비되는지 평가할 수 있습니다.
• Curated Layouts (큐레이션된 레이아웃): 즉시 시작할 수 있도록 비용(Cost), 지연 시간(Latency), 프롬프트(Prompts) 또는 평가(Evals)에 중점을 둔 사전 구축된 원클릭 템플릿을 제공합니다.

6. 프롬프트 관리 콘텐츠 시스템 (Prompt Management Content System)

대시보드는 로우코드(low-code) 프롬프트 레지스트리(registry) 역할도 수행합니다:

• Version Control (버전 관리): 핵심 코드베이스를 업데이트하지 않고도 시간이 지남에 따라 프롬프트의 변형을 생성, 테스트 및 추적할 수 있습니다.
• Playground Integration (플레이그라운드 통합): 실제 운영 중인 입력 트레이스(input trace)를 대화형 LLM 플레이그라운드(Playground) 내에서 직접 열어 프롬프트 수정을 테스트하고 모델 동작을 나란히 비교할 수 있습니다.

💡 데이터 이식성 참고 (Data Portability Note): Langfuse 외부에서 이 데이터를 시각화하는 것을 선호한다면, 플랫폼에 **Query API 엔드포인트(endpoint)**가 포함되어 있습니다. 이를 통해 대시보드 데이터베이스에서 모든 집계된 트레이스 메트릭(trace metric)을 직접 가져와 자체 내부 비즈니스 인텔리전스(BI) 도구(Tableau 또는 Looker 등)로 바로 전달할 수 있습니다.

설치 (Installation)

설치 예제는 제가 이전에 작성한 기사와 리포지토리(repository)를 기반으로 합니다 - NestJS와 LangGraph로 생성된 에이전트입니다.

https://dev.to/dan1618/building-ai-agent-with-langgraph-and-nestjs-4d86
https://github.com/Dan1618/nest-langgraph

Langfuse의 LLM 모니터링 및 관측성(observability) 솔루션은 두 부분으로 구성됩니다:

• Langfuse SDKs
• Langfuse Server

Langfuse SDKs는 다양한 플랫폼에서 사용할 수 있는 Langfuse의 코딩 측면으로, 애플리케이션 코드에서 계측(instrumentation)을 활성화할 수 있게 해줍니다. 이는 애플리케이션의 코드베이스에서 적절하게 사용할 수 있는 몇 줄의 코드에 불과합니다.

반면에 **Langfuse 서버 (Langfuse server)**는 UI 기반의 대시보드로, 모든 트레이스 (traces)와 메트릭 (metrics)을 기록(log), 조회 및 영구 저장(persist)하는 데 사용되는 기타 하위 서비스들과 함께 구성됩니다. Langfuse의 대시보드는 일반적으로 모든 현대적인 웹 브라우저를 통해 접속할 수 있습니다.

1. Docker를 이용한 Langfuse 서버 설정
가장 최신 정보를 제공하는 공식 문서를 따라 이 부분을 설치하는 것을 권장합니다.
https://langfuse.com/self-hosting/deployment/docker-compose
적절한 설치를 마친 후에는 새로운 프로젝트와 LANGFUSE_SECRET_KEY 및 LANGFUSE_PUBLIC_KEY를 생성할 수 있으며, 이는 Langfuse가 귀하의 애플리케이션을 인식할 수 있도록 .env 파일에 전달해야 합니다.

2. SDK 설치
https://langfuse.com/docs/observability/sdk/overview
제가 제공한 NestJS 앱의 예시에서는 다음과 같습니다:

a) .env 파일을 업데이트합니다.

LANGFUSE_SECRET_KEY=""
LANGFUSE_PUBLIC_KEY=""
LANGFUSE_BASE_URL="http://localhost:port"
...

b) OpenTelemetry (OTel)를 실행하는 파일을 생성하고 애플리케이션 시작 시 최상단에서 이를 초기화합니다.

import * as dotenv from 'dotenv';
dotenv.config(); // ← Langfuse / OTel 임포트가 환경 변수를 읽기 전에 반드시 실행되어야 함

...

c) 각 appGraph 호출 시 CallbackHandler를 추가합니다.

    // 각 호출은 고유한 핸들러를 가져 트레이스 (trace)가 올바르게 스코프 (scope) 지정됩니다.
    const langfuseHandler = new CallbackHandler({
      tags: ['langgraph', 'portfolio-review'],
...

실전 관측 (Observations in practice)

다음은 Langfuse 대시보드 덕분에 수행할 수 있는 몇 가지 관측 사례입니다.

아래 스크린샷에는 프롬프트 (prompt), 사용자 입력 (user input), LLM 출력 (llm output), 소요 시간 또는 토큰 사용량 (117)과 같은 가장 중요한 속성들과 함께 LLM 호출이 표시되어 있습니다:

여기에서 에이전트가 수행한 모든 작업에 대한 상세한 로그 테이블을 볼 수 있습니다. 이 테이블은 대화형이며, 필터링 및 사용자 정의가 가능합니다.

요약 (Summary)

이 포스트에서는 에이전트 시스템 (agentic systems) 관측성 (observability)의 기초를 다루었습니다. Langfuse의 주요 기능, LangGraph 통합 예시를 포함한 NestJS 앱 설치 가이드, 그리고 마지막으로 작동하는 에이전트 앱의 트레이싱 (tracing) 예시를 살펴보았습니다.