Logfire 통합

Logfire 통합 (Logfire Integration)

Pydantic Logfire로 평가 결과를 시각화하고 분석해요.

Pydantic Evals는 OpenTelemetry를 사용해 평가 과정의 트레이스를 기록해요. 이 트레이스에는 평가 보고서의 모든 정보와 작업 함수 실행의 전체 트레이싱이 담겨 있어요.

이 트레이스를 Pydantic Logfire를 포함한 어떤 OpenTelemetry 호환 백엔드로든 보낼 수 있어요.

출처: 문서

본문

설치

선택적 logfire 의존성을 설치해요:

Terminal

pip install 'pydantic-evals[logfire]'

기본 설정

평가를 실행하기 전에 Logfire를 구성해요:

basic_logfire_setup.py

import logfire

from pydantic_evals import Case, Dataset

# Logfire 구성
logfire.configure(
    send_to_logfire='if-token-present',  # (1)
)


# 평가 코드
def my_task(inputs: str) -> str:
    return f'result for {inputs}'


dataset = Dataset(name='logfire_demo', cases=[Case(name='test', inputs='example')])
report = dataset.evaluate_sync(my_task)

LOGFIRE_TOKEN 환경 변수가 설정된 경우에만 Logfire로 데이터를 보냄

그것뿐이에요! LOGFIRE_TOKEN 환경 변수가 설정되어 있으면 이제 평가 트레이스가 Logfire 웹 UI에 표시돼요.

Logfire로 보내지는 것

평가를 실행하면 Logfire는 다음을 받아요:

평가 메타데이터
1. 데이터셋 이름
2. 케이스 수
3. 평가자 이름
케이스별 데이터
1. 입력과 출력
2. 기대 출력
3. 메타데이터
4. 실행 기간
평가 결과
1. 점수, 판정, 라벨
2. 이유 (포함된 경우)
3. 평가자 실패
작업 실행 트레이스
1. 작업 함수의 모든 OpenTelemetry 스팬
2. 툴 호출 (Pydantic AI 에이전트의 경우)
3. API 호출, 데이터베이스 쿼리 등

Logfire에서 결과 보기

평가 개요

Logfire는 루트 평가 스팬에 평가 결과를 위한 특별한 테이블 뷰를 제공해요:

Logfire Evals Overview

이 뷰는 다음을 보여줘요:

케이스 이름
합격/불합격 상태
점수와 판정
실행 기간
빠른 필터링과 정렬

개별 케이스 상세

케이스를 클릭하면 상세한 입력과 출력을 볼 수 있어요:

Logfire Evals Case

전체 트레이스 뷰

평가 중에 생성된 모든 스팬을 포함한 전체 실행 트레이스를 봐요:

Logfire Evals Case Trace

이것은 특히 다음에 유용해요:

실패한 케이스 디버깅
성능 병목 이해
툴 사용 패턴 분석
스팬 기반 평가자 작성

트레이스 분석

실행 비교

같은 평가를 여러 번 실행하고 Logfire에서 비교해요:

from pydantic_evals import Case, Dataset


def original_task(inputs: str) -> str:
    return f'original result for {inputs}'


def improved_task(inputs: str) -> str:
    return f'improved result for {inputs}'


dataset = Dataset(name='comparison', cases=[Case(name='test', inputs='example')])

# 실행 1: 원래 구현
report1 = dataset.evaluate_sync(original_task)

# 실행 2: 개선된 구현
report2 = dataset.evaluate_sync(improved_task)

# 타임스탬프나 속성으로 필터링해 Logfire에서 비교

실패한 케이스 디버깅

실패한 케이스를 빠르게 찾아요:

service_name = 'my_service_evals' AND is_exception로 검색 (사용 중인 실제 서비스 이름으로 바꿔요)
전체 스팬 트리를 봐서 실패가 어디서 발생했는지 확인
오류 메시지에 대한 속성과 로그 검사

스팬 기반 평가

Logfire 통합은 강력한 스팬 기반 평가자를 가능하게 해요. 자세한 내용은 스팬 기반 평가를 참고해요.

예시: 특정 툴이 호출됐는지 확인:

import logfire

from pydantic_evals import Case, Dataset
from pydantic_evals.evaluators import HasMatchingSpan

logfire.configure(send_to_logfire='if-token-present')


def my_agent(inputs: str) -> str:
    return f'result for {inputs}'


dataset = Dataset(
    name='logfire_demo',
    cases=[Case(name='test', inputs='example')],
    evaluators=[
        HasMatchingSpan(
            query={'name_contains': 'search_tool'},
            evaluation_name='used_search',
        ),
    ],
)

report = dataset.evaluate_sync(my_agent)

스팬 트리는 둘 다에서 사용할 수 있어요:

평가자 코드 (ctx.span_tree 통해)
Logfire UI (시각적 트레이스 뷰)

문제 해결

Logfire에 데이터가 나타나지 않음

확인해요:

토큰이 설정됐는지: echo $LOGFIRE_TOKEN

구성이 올바른지:

import logfire

logfire.configure(send_to_logfire='always')  # 강제 전송

네트워크 연결: 방화벽 설정 확인
프로젝트가 존재하는지: Logfire UI에서 프로젝트 이름 확인

트레이스에 스팬이 누락됨

일부 스팬이 없다면:

import 전에 logfire가 구성됐는지 확인:

import logfire

logfire.configure()  # 반드시 첫 번째여야 함

계측 확인: 원하는 모든 계측이 활성화됐는지 확인:

import logfire

logfire.instrument_pydantic_ai()
logfire.instrument_httpx(capture_all=True)

모범 사례

1. 일찍 구성하기

평가를 실행하기 전에 항상 Logfire를 구성해요:

import logfire

from pydantic_evals import Case, Dataset

logfire.configure(send_to_logfire='if-token-present')


# 이제 import하고 평가 실행
def task(inputs: str) -> str:
    return f'result for {inputs}'


dataset = Dataset(name='logfire_demo', cases=[Case(name='test', inputs='example')])
dataset.evaluate_sync(task)

2. 설명적인 서비스 이름과 환경 사용하기

import logfire

logfire.configure(
    service_name='rag-pipeline-evals',
    environment='development',
)

3. 정기적으로 리뷰하기

패턴을 파악하려면 Logfire를 정기적으로 확인
일관되게 실패하는 케이스를 찾아보기
성능 추세 분석
인사이트에 기반해 평가자 조정

다음 단계

스팬 기반 평가 - 평가자에서 OpenTelemetry 스팬 사용
Logfire 문서 - 완전한 Logfire 가이드
메트릭 & 속성 - 트레이스에 커스텀 데이터 추가

더 알아보기 (Learn more)

Pydantic Evals 문서: Logfire 통합