Skip to main content
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

​
조직 생성부터 API 키 발급까지

컨테이너 실행 후 아래 순서로 초기 설정을 진행합니다.

​
1) 조직 생성

조직 이름을 입력하고 Create를 클릭합니다. Langfuse 조직 생성 화면

​
2) 멤버 초대

Invite members 단계에서 팀원을 초대합니다. 나중에 추가해도 됩니다. Langfuse 멤버 초대 화면

​
3) 프로젝트 생성

프로젝트 이름을 입력하고 Create를 클릭합니다. Langfuse 프로젝트 생성 화면

​
4) API 키 발급 화면으로 이동

프로젝트 홈의 Get started 섹션에서 Create new API key를 클릭합니다. Langfuse API 키 발급 시작 화면

​
5) API 키 발급 완료

Secret Key와 Public Key를 발급받고 안전한 위치에 저장합니다. Langfuse API 키 발급 완료 화면
API 키는 비밀번호처럼 관리합니다. 문서, 코드, 채팅에 원문 키를 그대로 공유하지 마세요.

​
기본 정보

항목값
웹 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 제한 대상

​
참고

​
설치 점검 목록

  • docker compose up -d 후 docker compose ps로 컨테이너 상태를 확인했습니다.
  • 기본 포트/계정/비밀번호를 문서대로 점검했습니다.
  • 운영용으로 사용할 때 기본 비밀번호/시크릿 값을 변경했습니다.
  • 장애 분석을 위해 docker compose logs -f 확인 방법을 숙지했습니다.

​
문제 해결 가이드

  • 컨테이너가 실행되지 않으면 docker compose logs -f로 오류 원인을 먼저 확인합니다.
  • 포트 충돌이 나면 기존 프로세스를 종료하거나 포트 매핑 값을 변경합니다.
  • 이미지 pull 실패 시 네트워크 연결 및 레지스트리 접근 권한을 확인합니다.
  • 설정 변경 후 문제가 지속되면 docker compose down 후 다시 up -d로 재기동합니다.

​
관련 문서

Setup 홈

운영체제별 설치 흐름을 다시 확인합니다.

다음: MLflow

다음 설치 단계를 이어서 진행합니다.