Langfuse 데이터 모델 (Observations·Traces·Sessions)

Langfuse 데이터 모델 (Observations·Traces·Sessions)

Langfuse가 앱 데이터를 어떻게 구조화하고 저장하는지 이해하면, 트레이스를 보고 디버깅하는 일이 훨씬 수월해져요. 데이터는 크게 세 개념—observations(관찰), traces(트레이스), sessions(세션)—으로 정리돼요. 이 페이지에서는 그 구조가 어떻게 쌓이는지, 그리고 OpenTelemetry 기반으로 어떻게 데이터가 실제 수집되는지까지 설명할게요.

출처: Langfuse Observability Data Model (Core Concepts)

Observations와 Traces

Observations(관찰) 는 애플리케이션의 개별 단계예요. LLM 호출, 도구 호출, 검색 단계처럼요. 서로 중첩될 수 있어 애플리케이션 구조를 그대로 반영하며, Langfuse는 generation·event 같은 LLM 특화 관찰 타입도 지원해요. Trace(트레이스) 는 단일 요청이나 연산 하나—예를 들면 사용자 질문부터 최종 응답까지의 채팅 인터랙션 한 건—를 뜻해요. 같은 trace_id를 공유하는 모든 관찰을 논리적으로 묶는 단위죠.

user_id, session_id, tags, metadata 같은 트레이스 수준 속성은 트레이스 안의 모든 관찰에 존재해요. SDK가 자동으로 전파하기 때문이죠. 개념적으로 Langfuse는 관찰 테이블 하나를 두고, 각 행에 관찰 데이터와 트레이스 수준 속성의 복사본을 담아요. 덕분에 쿼리·집계가 빠르게 유지돼요.

Sessions

선택 사항으로, 트레이스들을 세션으로 묶을 수 있어요. 세션은 같은 사용자 인터랙션에 속한 트레이스들을 그룹화하는 데 쓰여요. 대표적인 예가 채팅 인터페이스의 스레드죠. 멀티턴 대화나 워크플로우가 있는 애플리케이션이라면 세션 사용을 권장해요.

classDiagram
    Session "1" o-- "n" Trace

속성 붙이기 (Adding Attributes)

트레이스·관찰 구조를 잡았다면, 여기에 추가 속성으로 풍부하게 만들 수 있어요. 속성은 라벨처럼 작동해서 특정 용도로 트레이스를 필터·분석하는 데 도와줘요.

Langfuse가 데이터를 잡는 방식

OpenTelemetry 기반

Langfuse는 오픈 표준인 OpenTelemetry 위에 구축돼 있어요. 그래서 Langfuse 전용 SDK만 써야 하는 게 아니에요. 트레이스를 여러 목적지로 동시에 보낼 수도 있어요—LLM 관찰은 Langfuse로, 인프라 모니터링은 Datadog으로처럼요.

백그라운드 처리

앱 속도를 늦추지 않기 위해, Langfuse는 트레이스가 생기는 그 순간 동기적으로 보내지 않아요. 대신 트레이스를 로컬에서 배치로 모아 백그라운드에서 전송해요. 이 방식은 웹 서버나 API처럼 오래 돌아가는 애플리케이션에 잘 맞아요—백그라운드 익스포터가 계속 돌며 배치를 알아서 비워주니까요.

반면 시작→실행→종료가 빠른 단명 애플리케이션은, 큐에 아직 보내지 않은 트레이스가 있는 채로 프로세스가 끝나버릴 위험이 있어요. 데이터 손실을 막으려면 종료 전에 반드시 flush()를 명시적으로 호출해야 해요. 그래야 버퍼된 모든 트레이스를 즉시 전송한 뒤 프로세스가 끝나요.

더 알아보기 (Learn more)

• 트레이스·세션·관찰 데이터 모델
• 세션으로 멀티턴 대화 묶기
• OpenTelemetry 통합 가이드