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

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

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

1) 조직 생성

조직 이름을 입력하고 Create를 클릭합니다.

2) 멤버 초대

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

3) 프로젝트 생성

프로젝트 이름을 입력하고 Create를 클릭합니다.

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

프로젝트 홈의 Get started 섹션에서 Create new API key를 클릭합니다.

5) API 키 발급 완료

Secret Key와 Public Key를 발급받고 안전한 위치에 저장합니다.

API 키는 비밀번호처럼 관리합니다. 문서, 코드, 채팅에 원문 키를 그대로 공유하지 마세요.

기본 정보

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

포함된 서비스

서비스	역할
langfuse-web	웹 UI / API 서버
langfuse-worker	비동기 작업 처리
langfuse-db	PostgreSQL (메타데이터)
langfuse-clickhouse	ClickHouse (트레이스 데이터)
langfuse-redis	Redis (캐시, 큐)
langfuse-minio	MinIO (미디어 스토리지)

환경 변수

변수	설명
`DATABASE_URL`	PostgreSQL 연결 문자열
`NEXTAUTH_SECRET`	NextAuth 세션 암호화 키
`NEXTAUTH_URL`	외부 접속 URL
`SALT`	해시 솔트
`ENCRYPTION_KEY`	암호화 키 (64자 hex)
`CLICKHOUSE_URL`	ClickHouse 연결 URL
`REDIS_CONNECTION_STRING`	Redis 연결 문자열
`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

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

00. 배움 에이아이 소개

01. OS별 개발환경

02. 컨테이너 스택

03. Python 환경 설정

어디에 쓰이나요?

Docker Compose

실행

접속 확인

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

1) 조직 생성

2) 멤버 초대

3) 프로젝트 생성

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

5) API 키 발급 완료

기본 정보

포함된 서비스

환경 변수

SDK 연동

라이선스

참고

설치 점검 목록

문제 해결 가이드

관련 문서

Setup 홈

다음: MLflow

​어디에 쓰이나요?

​Docker Compose

​실행

​접속 확인

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

​1) 조직 생성

​2) 멤버 초대

​3) 프로젝트 생성

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

​5) API 키 발급 완료

​기본 정보

​포함된 서비스

​환경 변수

​SDK 연동

​라이선스

​참고

​설치 점검 목록

​문제 해결 가이드

​관련 문서

Setup 홈

다음: MLflow

어디에 쓰이나요?

Docker Compose

실행

접속 확인

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

1) 조직 생성

2) 멤버 초대

3) 프로젝트 생성

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

5) API 키 발급 완료

기본 정보

포함된 서비스

환경 변수

SDK 연동

라이선스

참고

설치 점검 목록

문제 해결 가이드

관련 문서