Skip to main content

​
Langfuse

LLM Observability(관측) 플랫폼입니다. LLM 애플리케이션의 동작을 추적하고 분석할 수 있습니다.

​
어디에 쓰이나요?

  • 트레이싱: LLM 호출의 입력, 출력, 소요 시간, 비용을 기록하고 시각화
  • 디버깅: RAG 파이프라인에서 어떤 문서가 검색되었는지, 프롬프트가 어떻게 구성되었는지 단계별로 추적
  • 프롬프트 관리: 프롬프트 템플릿의 버전 관리 및 배포
  • 평가(Evaluation): LLM 응답의 품질을 자동/수동으로 평가하고 점수 관리
  • 비용 분석: 모델별, 기능별 API 호출 비용 추적
LLM 애플리케이션은 프롬프트, 검색 결과, 모델 응답 등 여러 단계를 거쳐 최종 결과를 생성합니다. 문제가 발생했을 때 어떤 단계에서 잘못되었는지 파악하기 어려운데, Langfuse를 사용하면 각 단계를 **트레이스(Trace)**로 기록하고 웹 UI에서 확인할 수 있습니다.

​
Docker Compose

Langfuse v3는 PostgreSQL, ClickHouse, Redis, MinIO(S3 호환 스토리지)를 함께 사용합니다.
docker-compose.yml
services:
  langfuse-web:
    image: langfuse/langfuse:3
    container_name: langfuse-web
    restart: always
    ports:
      - "3000:3000"
    environment:
      - DATABASE_URL=postgresql://postgres:changeme@langfuse-db:5432/langfuse
      - NEXTAUTH_URL=http://localhost:3000
      - NEXTAUTH_SECRET=changeme
      - SALT=changeme
      - ENCRYPTION_KEY=0000000000000000000000000000000000000000000000000000000000000000
      - CLICKHOUSE_URL=http://langfuse-clickhouse:8123
      - CLICKHOUSE_USER=default
      - CLICKHOUSE_PASSWORD=changeme
      - REDIS_CONNECTION_STRING=redis://:changeme@langfuse-redis:6379/0
      - LANGFUSE_S3_BUCKET_NAME=langfuse
      - LANGFUSE_S3_ENDPOINT=http://langfuse-minio:9000
      - LANGFUSE_S3_ACCESS_KEY_ID=minioadmin
      - LANGFUSE_S3_SECRET_ACCESS_KEY=changeme
      - LANGFUSE_S3_REGION=auto
    depends_on:
      langfuse-db:
        condition: service_healthy
      langfuse-clickhouse:
        condition: service_healthy
      langfuse-minio:
        condition: service_healthy
      langfuse-redis:
        condition: service_healthy

  langfuse-worker:
    image: langfuse/langfuse:3
    container_name: langfuse-worker
    restart: always
    command: ["node", "packages/worker/dist/app.js"]
    environment:
      - DATABASE_URL=postgresql://postgres:changeme@langfuse-db:5432/langfuse
      - NEXTAUTH_URL=http://localhost:3000
      - NEXTAUTH_SECRET=changeme
      - SALT=changeme
      - ENCRYPTION_KEY=0000000000000000000000000000000000000000000000000000000000000000
      - CLICKHOUSE_URL=http://langfuse-clickhouse:8123
      - CLICKHOUSE_USER=default
      - CLICKHOUSE_PASSWORD=changeme
      - REDIS_CONNECTION_STRING=redis://:changeme@langfuse-redis:6379/0
      - LANGFUSE_S3_BUCKET_NAME=langfuse
      - LANGFUSE_S3_ENDPOINT=http://langfuse-minio:9000
      - LANGFUSE_S3_ACCESS_KEY_ID=minioadmin
      - LANGFUSE_S3_SECRET_ACCESS_KEY=changeme
      - LANGFUSE_S3_REGION=auto
    depends_on:
      langfuse-db:
        condition: service_healthy
      langfuse-clickhouse:
        condition: service_healthy
      langfuse-minio:
        condition: service_healthy
      langfuse-redis:
        condition: service_healthy

  langfuse-db:
    image: postgres:17-alpine
    container_name: langfuse-db
    restart: always
    environment:
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=changeme
      - POSTGRES_DB=langfuse
    ports:
      - "127.0.0.1:5432:5432"
    volumes:
      - langfuse_db_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 3s
      timeout: 3s
      retries: 10

  langfuse-redis:
    image: redis:7
    container_name: langfuse-redis
    restart: always
    command: ["redis-server", "--requirepass", "changeme"]
    ports:
      - "127.0.0.1:6379:6379"

  langfuse-clickhouse:
    image: clickhouse/clickhouse-server:24
    container_name: langfuse-clickhouse
    restart: always
    environment:
      - CLICKHOUSE_USER=default
      - CLICKHOUSE_PASSWORD=changeme
    ports:
      - "127.0.0.1:8123:8123"
    volumes:
      - langfuse_clickhouse_data:/var/lib/clickhouse
      - langfuse_clickhouse_logs:/var/log/clickhouse-server
    healthcheck:
      test: ["CMD", "wget", "--spider", "-q", "http://localhost:8123/ping"]
      interval: 3s
      timeout: 3s
      retries: 10

  langfuse-minio:
    image: minio/minio
    container_name: langfuse-minio
    restart: always
    command: server /data --console-address ":9090"
    environment:
      - MINIO_ROOT_USER=minioadmin
      - MINIO_ROOT_PASSWORD=changeme
    ports:
      - "9090:9090"
      - "127.0.0.1:9000:9000"
    volumes:
      - langfuse_minio_data:/data
    healthcheck:
      test: ["CMD", "mc", "ready", "local"]
      interval: 3s
      timeout: 3s
      retries: 10

volumes:
  langfuse_db_data:
  langfuse_clickhouse_data:
  langfuse_clickhouse_logs:
  langfuse_minio_data:
위 설정의 NEXTAUTH_SECRET, SALT, ENCRYPTION_KEY, 각 서비스의 비밀번호는 반드시 변경 후 사용하세요. ENCRYPTION_KEY는 64자 hex 문자열이어야 합니다.

​
실행

docker compose up -d
초기 기동 시 2~3분 정도 소요될 수 있습니다.

​
접속 확인

브라우저에서 http://localhost:3000으로 접속합니다. 초기 접속 시 회원가입 화면이 표시됩니다. 
# 로그 확인
docker compose logs -f langfuse-web

​
기본 정보

항목값
웹 UI 포트3000
MinIO Console 포트9090
데이터베이스PostgreSQL + ClickHouse
캐시Redis
오브젝트 스토리지MinIO

​
포함된 서비스

서비스역할
langfuse-web웹 UI / API 서버
langfuse-worker비동기 작업 처리
langfuse-dbPostgreSQL (메타데이터)
langfuse-clickhouseClickHouse (트레이스 데이터)
langfuse-redisRedis (캐시, 큐)
langfuse-minioMinIO (미디어 스토리지)

​
환경 변수

변수설명
DATABASE_URLPostgreSQL 연결 문자열
NEXTAUTH_SECRETNextAuth 세션 암호화 키
NEXTAUTH_URL외부 접속 URL
SALT해시 솔트
ENCRYPTION_KEY암호화 키 (64자 hex)
CLICKHOUSE_URLClickHouse 연결 URL
REDIS_CONNECTION_STRINGRedis 연결 문자열
LANGFUSE_S3_*MinIO/S3 스토리지 설정

​
SDK 연동

Langfuse에서 프로젝트를 생성하고 API 키를 발급받아 SDK에서 사용합니다. 
from langfuse import Langfuse

langfuse = Langfuse(
    public_key="pk-...",
    secret_key="sk-...",
    host="http://localhost:3000"
)

​
라이선스

구분내용
라이선스MIT (core), Elastic License 2.0 (일부 기능)
개인 사용자유롭게 사용 가능
상업적 사용사내 사용은 자유. Langfuse를 관리형 서비스(SaaS)로 제공하는 것은 ELv2 제한 대상

​
참고