Langfuse Metrics API — 추출 가능 데이터 리스트 (온프레미스 기준)

1. API 개요

항목 내용
Metrics API v1 GET /api/public/metrics
Daily Metrics API (레거시) GET /api/public/metrics/daily

v2 Metrics API (/api/public/v2/metrics)는 Langfuse Cloud 전용이므로 온프레미스에서는 사용할 수 없습니다.

2. 조회 가능한 View

View 설명
traces 트레이스(요청) 단위 데이터
observations Observation(개별 단계) 단위 데이터
scores-numeric 수치형/불린형 스코어
scores-categorical 범주형(문자열) 스코어

3. Trace 뷰

3-1. Dimensions (그룹핑/필터링 기준)

필드 타입 설명
id string 트레이스 ID
name string 트레이스 이름 (use case/기능 구분용)
tags string[] 트레이스 태그
userId string 사용자 ID
sessionId string 세션 ID
release string 릴리스 태그
version string 버전 태그
environment string 환경 (production, staging 등)
observationName string 관련 Observation 이름
scoreName string 관련 스코어 이름

3-2. Metrics (측정 지표)

지표 설명
count 트레이스 수
observationsCount 트레이스 내 Observation 수
scoresCount 트레이스 내 스코어 수
latency 트레이스 소요시간 (ms)
totalTokens 총 토큰 사용량
totalCost 총 비용 (USD)

4. Observation 뷰

4-1. Dimensions (그룹핑/필터링 기준)

필드 타입 설명
id string Observation ID
traceId string 상위 트레이스 ID
traceName string 상위 트레이스 이름
environment string 환경 (production, staging 등)
parentObservationId string 상위 Observation ID
type string Observation 유형 (generation, tool call 등)
name string Observation 이름
level string 로그 레벨
version string 버전
providedModelName string 사용된 모델 이름
promptName string 프롬프트 이름
promptVersion string 프롬프트 버전
userId string 사용자 ID (상위 trace에서 전파)
sessionId string 세션 ID (상위 trace에서 전파)
traceRelease string 릴리스 (상위 trace에서 전파)
traceVersion string 버전 (상위 trace에서 전파)
scoreName string 관련 스코어 이름

4-2. Metrics (측정 지표)

지표 설명
count Observation 수
latency Observation 소요시간 (ms)
totalTokens 총 토큰 사용량
totalCost 총 비용 (USD)
timeToFirstToken 첫 토큰까지 걸린 시간 (ms)
countScores 관련 스코어 수

5. Score 뷰

5-1. 공통 Dimensions (Numeric / Categorical 동일)

필드 타입 설명
id string 스코어 ID
name string 스코어 이름
environment string 환경
source string 스코어 소스 (API, SDK, LLM-as-a-Judge 등)
dataType string 데이터 타입
traceId string 관련 트레이스 ID
traceName string 관련 트레이스 이름
userId string 사용자 ID
sessionId string 세션 ID
observationId string 관련 Observation ID
observationName string 관련 Observation 이름
observationModelName string 관련 Observation의 모델명
observationPromptName string 관련 Observation의 프롬프트 이름
observationPromptVersion string 관련 Observation의 프롬프트 버전
configId string 설정 ID

5-2. Numeric Score Metrics

지표 설명
count 스코어 수
value 수치 값 (avg, sum, p50, p95 등으로 집계 가능)

5-3. Categorical Score Metrics

지표 설명
count 스코어 수

Categorical Score에는 stringValue (범주 문자열 값) dimension이 추가로 제공됩니다.

6. 집계(Aggregation) 방식

모든 metric에 아래 집계 방식을 적용할 수 있습니다.

집계 설명
sum 합계
avg 평균
count 건수
max 최댓값
min 최솟값
p50 50번째 백분위 (중앙값)
p75 75번째 백분위
p90 90번째 백분위
p95 95번째 백분위
p99 99번째 백분위

7. 시간 단위 (Time Granularity)

단위 설명
hour 시간별
day 일별
week 주별
month 월별
auto 자동 (기간에 따라 자동 결정)

8. Daily Metrics API (레거시)

GET /api/public/metrics/daily로 받을 수 있는 일별 집계 데이터입니다.

필드 설명
date 날짜
countTraces 트레이스 수
countObservations Observation 수
totalCost 총 비용 (USD)
usage[].model 모델 이름
usage[].inputUsage 입력 토큰 수
usage[].outputUsage 출력 토큰 수
usage[].totalUsage 총 토큰 수
usage[].countTraces 해당 모델의 트레이스 수
usage[].countObservations 해당 모델의 Observation 수
usage[].totalCost 해당 모델의 비용 (USD)

필터 옵션: traceName, userId, tags, fromTimestamp, toTimestamp

9. 위 데이터로 뽑을 수 있는 지표 정리

9-1. 비용 분석

지표 사용 데이터 산출 방법
일별/주별/월별 총 비용 totalCost × timeDimension traces 또는 observations 뷰에서 totalCost를 sum 집계, 시간 단위로 그룹핑
모델별 비용 비중 totalCost × providedModelName observations 뷰에서 모델명으로 그룹핑 후 totalCost sum
사용자별 비용 totalCost × userId traces 뷰에서 userId로 그룹핑 후 totalCost sum
기능별 비용 totalCost × name 또는 tags traces 뷰에서 traceName/tags로 그룹핑 후 totalCost sum
프롬프트 버전별 비용 변화 totalCost × promptVersion observations 뷰에서 promptVersion으로 그룹핑
환경별 비용 (prod vs staging) totalCost × environment environment 필터 또는 그룹핑 적용
요청 1건당 평균 비용 totalCost ÷ count totalCost sum / count로 계산

9-2. 성능(속도) 분석

지표 사용 데이터 산출 방법
평균 응답 시간 latency traces 뷰에서 latency를 avg 집계
P95/P99 응답 시간 latency traces 뷰에서 latency를 p95/p99 집계
모델별 응답 시간 비교 latency × providedModelName observations 뷰에서 모델명으로 그룹핑
첫 토큰 응답 시간 (TTFT) timeToFirstToken observations 뷰에서 avg/p95 집계
시간대별 응답 시간 추이 latency × timeDimension 시간 단위로 그룹핑하여 트렌드 확인
릴리스/버전별 성능 변화 latency × release 또는 version 버전 그룹핑으로 배포 전후 비교
기능별 응답 시간 latency × traceName traceName으로 그룹핑하여 기능 간 비교

9-3. 토큰 사용량 분석

지표 사용 데이터 산출 방법
일별 총 토큰 사용량 totalTokens × timeDimension traces/observations 뷰에서 sum 집계
모델별 토큰 사용량 totalTokens × providedModelName observations 뷰에서 모델명 그룹핑
Input vs Output 토큰 비율 inputUsage, outputUsage Daily Metrics API에서 모델별 input/output 비교
요청 1건당 평균 토큰 수 totalTokens ÷ count totalTokens sum / count로 계산
사용자별 토큰 소비량 totalTokens × userId traces 뷰에서 userId 그룹핑

9-4. 트래픽/볼륨 분석

지표 사용 데이터 산출 방법
일별/시간별 요청 수 count × timeDimension traces 뷰에서 count 집계, 시간 단위 그룹핑
기능별 요청 분포 count × name traces 뷰에서 traceName으로 그룹핑
사용자별 요청 수 count × userId traces 뷰에서 userId 그룹핑
모델별 호출 수 count × providedModelName observations 뷰에서 모델명 그룹핑
요청 1건당 평균 Observation 수 observationsCount traces 뷰에서 observationsCount avg 집계
환경별 트래픽 비교 count × environment environment로 그룹핑

9-5. 품질 분석

지표 사용 데이터 산출 방법
평균 품질 점수 value (scores-numeric) scores-numeric 뷰에서 value를 avg 집계
품질 점수 분포 value (scores-numeric) p50, p75, p90, p95로 분포 파악
모델별 품질 비교 value × observationModelName scores-numeric 뷰에서 모델명 그룹핑
프롬프트 버전별 품질 변화 value × observationPromptVersion 프롬프트 버전 그룹핑으로 A/B 비교
긍정/부정 피드백 비율 count × stringValue (scores-categorical) scores-categorical 뷰에서 stringValue 그룹핑
시간 경과에 따른 품질 추이 value × timeDimension 시간 단위로 품질 점수 트렌드 확인
평가 소스별 점수 비교 value × source source(API, LLM-Judge, 사람평가 등) 그룹핑
사용자별 만족도 value × userId userId 그룹핑으로 사용자별 품질 확인

9-6. 복합 지표 (여러 데이터 조합)

지표 사용 데이터 산출 방법
비용 대비 품질 효율 totalCost + value 모델/프롬프트별 비용과 품질 점수를 함께 조회하여 비교
속도 대비 품질 트레이드오프 latency + value 모델별 latency와 품질 점수를 함께 비교
릴리스별 종합 성과 latency + totalCost + value × release 릴리스 그룹핑으로 속도·비용·품질 동시 비교
이상 탐지 (Anomaly) latency p99 + totalCost max 극단값 집계로 비정상 요청 식별
사용자 활성도 count × userId × timeDimension 시간대별 사용자당 요청 수 추이

results matching ""

    No results matching ""

    results matching ""

      No results matching ""