CODE_ASSISTANT/5_django_backend/docs-lib/langfuse.md

Langfuse — 자체 호스팅 ingestion API (2026-09-22 정리)

출처: https://cloud.langfuse.com/generated/api/openapi.yml, langfuse.com/self-hosting. SDK 안 쓰고 HTTP 로 직접 쏨(오프라인 wheels 반입 줄이려고).

POST /api/public/ingestion

• 인증: Basic auth — user = pk-lf-…(public key), password = sk-lf-…(secret key)
• 응답: 207 (배치 부분 성공). 각 이벤트 결과가 successes[]/errors[] 로 옴
• Langfuse Cloud 에선 2026-11-16 폐기 예정이지만 self-host 는 계속 지원. OTel 엔드포인트(/api/public/otel/v1/traces)는 v3+ 만.

{
  "batch": [
    {"id": "evt-1", "timestamp": "2026-09-22T01:00:00Z", "type": "trace-create",
     "body": {"id": "trace-1", "name": "chat", "userId": "u@x.com", "sessionId": "ses_…", "input": "…", "output": "…", "metadata": {}, "tags": []}},
    {"id": "evt-2", "timestamp": "2026-09-22T01:00:05Z", "type": "generation-create",
     "body": {"id": "gen-1", "traceId": "trace-1", "name": "fabrix", "model": "581",
              "startTime": "…", "endTime": "…", "input": [...messages], "output": "…",
              "usage": {"input": 120, "output": 30, "total": 150}, "level": "DEFAULT", "statusMessage": "", "metadata": {}}}
  ]
}

• envelope: id(중복 제거용, 유일), timestamp(ISO 8601), type, body
• 이벤트 타입: trace-create, generation-create, span-create, event-create, score-create, *-update
• TraceBody: id·name·userId·sessionId·input·output·metadata·tags·version·release·environment·public
• CreateGenerationBody: id·traceId·name·startTime·endTime·completionStartTime·model·modelParameters·input·output·usage{input,output,total,unit,inputCost,outputCost,totalCost}·usageDetails·costDetails·level(DEBUG/DEFAULT/WARNING/ERROR)·statusMessage·metadata·parentObservationId
• 같은 traceId 로 trace-create 를 여러 번 보내도 됨(upsert). generation 먼저 와도 trace 가 나중에 붙음.

자체 호스팅 (v4 docker-compose, 2026-09 기준)

이미지 6개: langfuse/langfuse:4, langfuse/langfuse-worker:4, clickhouse/clickhouse-server:25.12, cgr.dev/chainguard/minio, redis:7, postgres:17. web 포트 3000. 필수 env: DATABASE_URL, NEXTAUTH_URL, NEXTAUTH_SECRET, SALT, ENCRYPTION_KEY(hex 64자), CLICKHOUSE_, REDIS_, LANGFUSE_S3_*.

헤드리스 초기화(첫 기동 때 조직·프로젝트·키·관리자 자동 생성, UI 클릭 없이): LANGFUSE_INIT_ORG_ID, LANGFUSE_INIT_ORG_NAME, LANGFUSE_INIT_PROJECT_ID, LANGFUSE_INIT_PROJECT_NAME, LANGFUSE_INIT_PROJECT_PUBLIC_KEY(pk-lf-…), LANGFUSE_INIT_PROJECT_SECRET_KEY(sk-lf-…), LANGFUSE_INIT_USER_EMAIL, LANGFUSE_INIT_USER_NAME, LANGFUSE_INIT_USER_PASSWORD. → 우리 deploy/langfuse/.env 가 이걸 채우고, 같은 pk/sk 를 백엔드 .env 의 LANGFUSE_* 에 넣음.