메트릭 API

메트릭 API (Metrics API)

GET /api/public/v2/metrics

Metrics API를 사용하면 Langfuse 데이터에서 커스터마이즈된 분석을 검색할 수 있어요. 이 엔드포인트로 차원, 메트릭, 필터, 시간 세분성을 지정해 LLM 애플리케이션용 강력한 커스텀 리포트와 대시보드를 만들 수 있어요.

출처: 문서

본문

GET /api/public/v2/metrics

Metrics API를 사용하면 Langfuse 데이터에서 커스터마이즈된 분석을 검색할 수 있어요. 이 엔드포인트는 차원, 메트릭, 필터, 시간 세분성을 지정해 LLM 애플리케이션용 강력한 커스텀 리포트와 대시보드를 만들 수 있게 해줘요.

할 수 있는 일 (What you can do)

Metrics API로 다음을 할 수 있어요:

비용, 토큰 사용량, 볼륨, 지연시간, 점수 데이터를 집계해요.
모델이나 trace 속성 같은 지원 차원으로 결과를 그룹화해요.
데이터를 필터링하고 시간 경과에 따른 추세를 분석해요.
커스텀 리포트, 대시보드, 빌링, 모니터링 워크플로를 구동해요.

지원되는 뷰, 필드, 쿼리 파라미터, 응답 스키마, 상호작용 예시는 v2 Metrics API Reference를, 실용적인 Python 예시는 Metrics API v2 cookbook을 참고하세요.

폐기된 GET /api/public/metrics와 GET /api/public/metrics/daily 엔드포인트는 마이그레이션 단계와 함께 Migration of deprecated APIs에 문서화되어 있어요.

Metrics API v2

이 기능은 어디서 사용할 수 있나요?

Hobby: 사용 가능
Core: 사용 가능
Pro: 사용 가능
Enterprise: 사용 가능
Self Hosted: Langfuse v4+

데이터 가용성: x-langfuse-ingestion-version: 4를 보내지 않는 이전 SDK(langfuse-python < 4.7.0, langfuse-js < 5.4.0)나 직접 OpenTelemetry exporter의 데이터는 v2 엔드포인트에서 최대 15분 지연될 수 있어요. Python SDK v4.7.0+, JS/TS SDK v5.4.0+로 업그레이드하거나, OTEL span exporter에 그 헤더를 설정해 실시간으로 새 데이터를 보세요. 상세: Versions & Compatibility. 셀프호스팅 Langfuse v3에서는 Metrics API v1을 대신 사용하세요(셀프호스팅 호환성 매트릭스 참고).

v2 Metrics API는 넓은 observations 테이블 위에 구축된 최적화된 데이터 아키텍처 덕분에 쿼리당 데이터베이스 작업을 최소화하는 상당한 성능 개선을 제공해요.

v1에서 바뀐 핵심 사항 (Key Changes from v1)

traces 뷰는 v2에서 더 이상 제공되지 않아요. 대신 v1보다 더 빠르고 강력한 observations 뷰를 사용하세요.

v2에서 제공되는 뷰 (Available Views in v2)

View	Description
observations	observation 레벨 데이터 조회 (선택적 trace 레벨 집계 포함)
scores-numeric	숫자 점수 조회
scores-categorical	범주형(문자열) 점수 조회
scores-boolean	불리언 점수 조회; booleanValue로 그룹·필터링하거나, true 비율로 평균값 사용

행 제한 (Row Limit)

v2 Metrics API는 일관된 성능을 보장하기 위해 기본 config.row_limit 100행을 적용해요. 쿼리에 커스텀 config.row_limit를 지정해 최대 1,000행까지 이 기본값을 재정의할 수 있어요.

고카디널리티 차원 (High Cardinality Dimensions)

id, traceId, userId, sessionId 같은 특정 차원은 v2 Metrics API에서 그룹핑에 사용할 수 없어요. 이런 고카디널리티 필드로 그룹화하는 것은 매우 비싸고 실전에서 거의 유용하지 않아요. 이 차원들은 필터링에는 계속 사용할 수 있어요.

의미론적 루트 필터링 및 그룹핑 (Semantic-root filtering and grouping)

v2 전용 isRootObservation 불리언 차원은 애플리케이션 진입점을 식별해요. true는 부모가 없는 외부 루트와, OpenTelemetry 계측·인프라 부모가 SDK에 의해 export에서 필터링된 앱 루트를 모두 포함해요. 후자의 경우를 놓치지 않고 애플리케이션 진입점을 세거나 필터링·그룹화하는 데 사용하세요. 물리적·논리적 루트의 구분과 trace-카운팅 엣지 케이스는 Logical root observations를 참고하세요.

[
  {
    "column": "isRootObservation",
    "operator": "=",
    "value": true,
    "type": "boolean"
  }
]

예를 들어, 쿼리의 filters 배열에 이 조건을 추가해 의미론적 루트를 세세요.

메트릭으로 정렬 (Ordering by metrics)

집계 메트릭으로 정렬할 때는 반환된 메트릭 필드 이름을 {aggregation}_{measure} 형식으로 사용하세요. 예: { "measure": "totalCost", "aggregation": "sum" }이면 sum_totalCost. 시간 차원으로 정렬할 때는 반환된 필드 이름 time_dimension을 사용하세요.

예시: observation에서 사용된 가장 비싼 모델 (Example: Most expensive models used in observations)

curl \
  -H "Authorization: Basic *** AUTH HEADER>" \
  -G \
  --data-urlencode 'query={
    "view": "observations",
    "metrics": [{"measure": "totalCost", "aggregation": "sum"}],
    "dimensions": [{"field": "providedModelName"}],
    "filters": [],
    "fromTimestamp": "2025-12-01T00:00:00Z",
    "toTimestamp": "2025-12-16T00:00:00Z",
    "orderBy": [{"field": "sum_totalCost", "direction": "desc"}],
    "config": {"row_limit": 1000}
  }' \
  https://cloud.langfuse.com/api/public/v2/metrics

더 알아보기 (Learn more)

출처 문서: 메트릭 API (Metrics API)