Pydantic Logfire Debugging and Monitoring

이 문서에서는 Pydantic Logfire를 사용해 Pydantic AI 애플리케이션을 디버깅하고 모니터링하는 방법을 알려드려요. Logfire는 Pydantic Validation과 Pydantic AI를 만들고 유지하는 팀이 개발한 관찰 가능성 플랫폼으로, OpenTelemetry를 사용해 전체 애플리케이션을 이해할 수 있게 해요.

출처: 문서

본문

LLM을 사용하는 애플리케이션은 잘 알려져 있고 이해된 몇 가지 어려움이 있어요. LLM은 느리고, 신뢰할 수 없으며, 비쌉니다.

이 애플리케이션은 또한 대부분의 개발자가 훨씬 덜 자주 만나는 어려움도 있어요. LLM은 변덕스럽고 비결정적이에요. 프롬프트의 미묘한 변화가 모델의 성능을 완전히 바꿀 수 있고, 왜 그런지 이해할 수 있는 EXPLAIN 쿼리를 실행할 방법이 없어요.

Warning

소프트웨어 엔지니어 관점에서 LLM을 당신이 들어본 최악의 데이터베이스보다 더 나쁜 것으로 생각할 수 있어요.

LLM이 그렇게 몹시 유용하지 않았다면, 우리는 그것을 절대 건드리지 않았을 거예요.

LLM으로 성공적인 애플리케이션을 구축하려면, 모델 성능과 그것에 의존하는 애플리케이션의 동작을 모두 이해할 수 있는 새 도구가 필요해요.

모델이 어떻게 성능을 내는지 이해하게 해주는 LLM 관찰 가능성 도구만으로는 쓸모없어요. LLM에 API 호출을 하는 것은 쉽고, 어려운 것은 그것을 애플리케이션에 구축하는 것이니까요.

Pydantic Logfire

Pydantic Logfire는 Pydantic Validation과 Pydantic AI를 만들고 유지하는 팀이 개발한 관찰 가능성 플랫폼이에요. Logfire는 전체 애플리케이션을 이해하게 해주는 것을 목표로 해요. Gen AI, 고전 예측 AI, HTTP 트래픽, 데이터베이스 쿼리, 그리고 현대 애플리케이션이 필요로 하는 그 밖의 모든 것, 모두 OpenTelemetry를 사용해요.

Pydantic Logfire는 상업 제품이에요

Logfire는 상업적으로 지원되는 호스팅 플랫폼이며, 매우 관대하고 영구적인 무료 티어가 있어요. 가입하고 몇 분 만에 Logfire를 쓰기 시작할 수 있어요. Logfire는 엔터프라이즈 티어에서 자체 호스팅할 수도 있어요.

Pydantic AI는 Logfire에 대한 내장된(하지만 선택적인) 지원이 있어요. 그것은 logfire 패키지가 설치·구성되고 에이전트 계측이 활성화되면 에이전트 실행에 대한 상세 정보가 Logfire로 전송된다는 뜻이에요. 그렇지 않으면 실질적으로 오버헤드가 없고 아무것도 전송되지 않아요.

Logfire에서 Weather Agent를 실행한 세부정보를 보여주는 예시예요:

Weather Agent Logfire

에이전트 실행에 대한 트레이스가 생성되고, 각 모델 요청과 도구 호출에 대해 스팬이 방출돼요.

Using Logfire

Logfire를 사용하려면 Logfire 계정이 필요해요. Logfire Python SDK는 pydantic-ai에 포함돼요:

Terminal

pip install pydantic-ai

Terminal

uv add pydantic-ai

또는 slim 패키지를 사용한다면 logfire 옵션 그룹으로 설치할 수 있어요:

Terminal

pip install "pydantic-ai-slim[logfire]"

Terminal

uv add "pydantic-ai-slim[logfire]"

그런 다음 Logfire로 로컬 환경을 인증하세요:

Terminal

 logfire auth

Terminal

uv run logfire auth

그리고 데이터를 보낼 프로젝트를 구성하세요:

Terminal

 logfire projects new

Terminal

uv run logfire projects new

(또는 logfire projects use로 기존 프로젝트 사용)

이렇게 하면 현재 작업 디렉터리에 .logfire 디렉터리가 생기며, Logfire SDK가 런타임에 구성을 위해 사용해요.

이제 Logfire를 사용해 Pydantic AI 코드를 계측할 수 있어요:

instrument_pydantic_ai.py

import logfire

from pydantic_ai import Agent

logfire.configure()  # (1)
logfire.instrument_pydantic_ai()  # (2)

agent = Agent('openai:gpt-5.2', name='hello_world_agent', instructions='Be concise, reply with one sentence.')  # (4)
result = agent.run_sync('Where does "hello world" come from?')  # (3)
print(result.output)
"""
The first known use of "hello, world" was in a 1974 textbook about the C programming language.
"""

logfire.configure()은 SDK를 구성하고, 기본적으로 .logfire 디렉터리에서 write 토큰을 찾지만 토큰을 직접 전달할 수도 있어요.

logfire.instrument_pydantic_ai()은 Pydantic AI의 계측을 활성화해요.

계측을 활성화했으므로, 각 실행에 대해 트레이스가 생성되고, 모델 호출과 도구 함수 실행에 대해 스팬이 방출돼요.

name을 전달하는 것은 선택적이지만 권장돼요. Logfire에서 에이전트의 실행 스팬에 라벨을 붙여요. 생략하면 에이전트가 할당된 변수에서 이름이 추론되고, 그럴 수 없으면(예: 목록이나 dict에 보관된 에이전트) 'agent'로 폴백돼요. 이것은 한 앱에서 여러 에이전트가 실행되고 그 트레이스를 구분해야 할 때 가장 중요해요.

(이 예시는 완전한 코드로, "그대로" 실행할 수 있어요)

그러면 Logfire에서 이렇게 표시돼요:

Logfire Simple Agent Run

Logfire 문서는 Logfire 사용 방법에 대한 더 많은 세부사항이 있으며, HTTPX와 FastAPI 같은 다른 라이브러리를 계측하는 방법도 포함해요.

Logfire는 OpenTelemetry 위에 구축되므로, Logfire Python SDK를 사용해 어떤 OpenTelemetry collector로든 데이터를 보낼 수 있어요. 아래를 참고하세요.

Debugging

Logfire가 Pydantic AI 실행의 흐름을 시각화하게 하는 방법을 보여주기 위해, chat app 예시를 실행하는 동안 Logfire에서 얻는 뷰가 여기 있어요:

Realtime(음성 대 음성) 세션은 같은 logfire.instrument_pydantic_ai() 호출로 계측돼요. 라이브 대화가 펼쳐짐에 따라 세션이 에이전트 실행으로 나타나고 그 자식 스팬이 각 모델 응답, 도구 호출, 턴 경계를 표시해요.

Monitoring Performance

Logfire에서 SQL로 데이터를 쿼리해 애플리케이션의 성능을 모니터링할 수도 있어요. Logfire 자체 내부에서 Pydantic AI 실행을 모니터링하는 데 Logfire를 사용하는 실제 세계 예시예요:

Logfire monitoring Pydantic AI

Monitoring HTTP Requests

Hamel Husain의 영향력 있는 2024 블로그 포스트 "Fuck You, Show Me The Prompt."에 따르면(대문자 표기법은 참아주세요, 요점은 타당해요), 모델 프로바이더에 보낸 원시 HTTP 요청과 응답을 볼 수 있는 것이 자주 유용해요.

모델 프로바이더에 보낸 원시 HTTP 요청을 관찰하려면 Logfire의 HTTPX 계측을 사용할 수 있어요. 프로바이더 SDK는 내부적으로 httpx 또는 httpx2를 사용하며, boto3를 사용하는 Bedrock은 예외예요:

with_logfire_instrument_httpx.py

import logfire

from pydantic_ai import Agent

logfire.configure()
logfire.instrument_pydantic_ai()
logfire.instrument_httpx(capture_all=True)  # (1)

agent = Agent('openai:gpt-5.2')
result = agent.run_sync('What is the capital of France?')
print(result.output)
#> The capital of France is Paris.

자세한 내용은 logfire.instrument_httpx 문서를 참고하세요. capture_all=True는 요청과 응답 둘 다에 대해 헤더와 본문이 모두 캡처된다는 뜻이에요.

httpx2 계측은 logfire extra가 설치해주는 opentelemetry-instrumentation-httpx>=0.65b0이 필요해요. OpenTelemetry를 직접 고정하고 그 버전 아래로 떨어지면, logfire.instrument_httpx()가 누락된 요구사항을 보고하고 httpx2 스팬을 방출하지 않아요.

Logfire with HTTPX instrumentation

Using OpenTelemetry

Pydantic AI의 계측은 Logfire의 기반인 OpenTelemetry(OTel)를 사용해요.

이것은 어떤 OpenTelemetry 백엔드로든 Pydantic AI를 디버깅하고 모니터링할 수 있다는 뜻이에요.

Pydantic AI는 Generative AI 시스템을 위한 OpenTelemetry Semantic Conventions을 따르므로, Logfire 플랫폼을 사용하면 최고의 경험을 얻을 거라고 생각하지만 😉, GenAI 지원이 있는 어떤 OTel 서비스도 사용할 수 있어야 해요.

Logfire with an alternative OTel backend

Logfire SDK를 완전히 자유롭게 사용하고 데이터를 어떤 OpenTelemetry 백엔드로든 보낼 수 있어요.

Logfire 라이브러리를 구성해 훌륭한 otel-tui(오픈소스 터미널 기반 OTel 백엔드·뷰어, Pydantic Validation과 무관)로 데이터를 보내는 예시예요.

docker로 otel-tui를 실행하고(otel-tui readme 참고):

Terminal

docker run --rm -it -p 4318:4318 --name otel-tui ymtdzzz/otel-tui:latest

그 다음 실행:

otel_tui.py

import os

import logfire

from pydantic_ai import Agent

os.environ['OTEL_EXPORTER_OTLP_ENDPOINT'] = 'http://localhost:4318'  # (1)
logfire.configure(send_to_logfire=False)  # (2)
logfire.instrument_pydantic_ai()
logfire.instrument_httpx(capture_all=True)

agent = Agent('openai:gpt-5.2')
result = agent.run_sync('What is the capital of France?')
print(result.output)
#> Paris

OTEL_EXPORTER_OTLP_ENDPOINT 환경 변수를 OpenTelemetry 백엔드의 URL로 설정하세요. 인증이 필요한 백엔드를 사용한다면 다른 환경 변수를 설정해야 할 수 있어요. 물론, 이것들은 프로세스 밖에서도 설정할 수 있어요. 예: export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318.

Logfire를 구성해 Logfire OTel 백엔드 자체로 데이터를 보내는 것을 비활성화해요. send_to_logfire=False를 제거하면 데이터가 Logfire와 OpenTelemetry 백엔드 둘 다로 전송돼요.

위 코드를 실행하면 추적 데이터가 otel-tui로 전송되며, 이렇게 표시돼요:

otel tui simple

otel-tui에 연결된 weather agent 예시를 실행하면 더 복잡한 트레이스를 시각화하는 데 어떻게 사용되는지 보여줘요:

otel tui weather agent

Logfire SDK로 대체 백엔드에 데이터를 보내는 방법에 대한 자세한 내용은 Logfire 문서를 참고하세요.

OTel without Logfire

Logfire를 전혀 사용하지 않고 Pydantic AI에서 OpenTelemetry 데이터를 방출할 수도 있어요.

이를 위해 필요한 OpenTelemetry 패키지를 설치·구성해야 해요. 다음 예시를 실행하려면:

Terminal

uv run \
  --with 'pydantic-ai-slim[openai]' \
  --with opentelemetry-sdk \
  --with opentelemetry-exporter-otlp \
  raw_otel.py

raw_otel.py

import os

from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.trace import set_tracer_provider

from pydantic_ai import Agent

os.environ['OTEL_EXPORTER_OTLP_ENDPOINT'] = 'http://localhost:4318'
exporter = OTLPSpanExporter()
span_processor = BatchSpanProcessor(exporter)
tracer_provider = TracerProvider()
tracer_provider.add_span_processor(span_processor)

set_tracer_provider(tracer_provider)

Agent.instrument_all()
agent = Agent('openai:gpt-5.2')
result = agent.run_sync('What is the capital of France?')
print(result.output)
#> Paris

Alternative Observability backends

Pydantic AI는 관찰 가능성에 OpenTelemetry를 사용하므로, 관찰 가능성 플랫폼 Pydantic Logfire뿐 아니라 어떤 OpenTelemetry 호환 백엔드로든 데이터를 보내도록 쉽게 구성할 수 있어요.

다음 프로바이더는 Pydantic AI에 대한 전용 문서가 있어요:

Advanced usage

Emitted metrics

스팬 외에도 계측은 다음 OpenTelemetry 메트릭을 기록하며, 모두 히스토그램이에요:

Metric

Unit

Description

gen_ai.client.token.usage

{token}

모델 또는 임베딩 요청당 사용된 토큰 수. gen_ai.token.type 속성(input 또는 output)으로 분할. GenAI semantic conventions가 정의.

operation.cost

{USD}

각 모델 또는 임베딩 요청의 추정 금전 비용. 모델에 대해 값이 알려질 때 기록.

gen_ai.client.operation.time_to_first_chunk

s

스트리밍 요청 발행부터 첫 청크가 소비자에게 표면화될 때까지의 시간. 스트리밍 요청에 대해서만 기록. 같은 값은 모델 요청 스팬의 같은 이름 속성으로도 설정.

각 메트릭 포인트는 gen_ai.provider.name(및 레거시 gen_ai.system), gen_ai.operation.name, gen_ai.request.model, gen_ai.response.model 속성을 지니므로, 히스토그램을 프로바이더와 모델별로 세분화할 수 있어요.

안정성과 히스토그램 버킷

gen_ai.client.operation.time_to_first_chunk은 현재 GenAI semantic conventions에서 Development 안정성에 있어, 안정화 전에 이름이나 모양이 바뀔 수 있어요. gen_ai.client.token.usage와 gen_ai.client.operation.time_to_first_chunk 둘 다 conventions가 지정한 명시적 버킷 경계를 권고해요. 이것은 권고일 뿐이에요. MeterProvider에 View를 구성해 재정의할 수 있고, 지수 히스토그램 집계용으로 구성된 SDK(Logfire 등)는 그것을 완전히 무시해요.

Aggregated usage attribute names

기본적으로 모델 요청 스팬은 표준 gen_ai.usage.input_tokens와 gen_ai.usage.output_tokens 속성을 사용하고, 에이전트 실행 스팬은 gen_ai.aggregated_usage.input_tokens, gen_ai.aggregated_usage.output_tokens, gen_ai.aggregated_usage.details.*를 사용해요.

이는 에이전트 실행 스팬이 자체 모델 요청 스팬의 usage 합계를 보고하므로, 부모·자식 스팬에 걸쳐 usage 속성을 집계하는 관찰 가능성 백엔드에서 이중 계산을 피해요.

에이전트 실행 스팬은 그 실행이 지출한 것을 보고해요. 다른 에이전트에 위임하는 실행은 위임자의 토큰을 포함하지 않아요. 위임자의 자체 실행 스팬이 그 토큰을 보고하니까요. 따라서 트레이스의 에이전트 실행 스팬은 있는 그대로 더할 수 있어요. 합계가 그 아래 모델 요청 스팬의 gen_ai.usage.* 속성 합과 일치해요.

커스텀 네임스페이스

gen_ai.aggregated_usage.* 네임스페이스는 OpenTelemetry Semantic Conventions for GenAI의 일부가 아닌 커스텀 확장이에요. 관찰 가능성 백엔드의 이중 계산을 해결하기 위해 도입됐어요. OpenTelemetry가 미래에 집계 usage에 대한 공식 관례를 도입하면, 이 네임스페이스는 갱신되거나 deprecate될 수 있어요.

에이전트 실행 스팬이 표준 gen_ai.usage.* 속성을 사용하고 백엔드에서 이중 계산을 처리하고 싶다면, 집계 usage 속성 이름을 비활성화하세요:

from pydantic_ai import Agent
from pydantic_ai.models.instrumented import InstrumentationSettings

Agent.instrument_all(InstrumentationSettings(use_aggregated_usage_attribute_names=False))

Configuring data format

Pydantic AI는 Generative AI 시스템을 위한 OpenTelemetry Semantic Conventions을 따르며, 특히 conventions 버전 1.37.0을 따릅니다. 계측 형식은 InstrumentationSettings의 version 파라미터로 구성할 수 있어요.

기본값은 version=5이에요.

버전 2, 3, 4는 deprecate된 호환성 형식이에요. 이 버전 중 하나를 InstrumentationSettings에 전달하면 PydanticAIDeprecationWarning을 발생시켜요. 더 오래된 텔레메트리 파이프라인을 일시적으로 보존하지 않는 한 버전 5를 사용하세요.

버전 6은 옵트인이에요. 이미 받는 메시지의 역할을 바꾸므로, 텔레메트리 소비자가 새 역할에 준비되면 명시적으로 전달하세요.

Version 2 (deprecated)

더 새로운 OpenTelemetry GenAI spec을 사용하고 다음 속성에 메시지를 저장해요:

에이전트에 전달된 지침용 gen_ai.system_instructions
모델 요청 스팬의 gen_ai.input.messages 및 gen_ai.output.messages
에이전트 실행 스팬의 pydantic_ai.all_messages

일부 스팬·속성 이름은 호환 이유로 spec을 완전히 따르지 않아요. 현재 텔레메트리에는 버전 5를 사용하세요.

Version 3 (deprecated)

다음 개선으로 버전 2 위에 구축돼요:

Spec 준수 스팬 이름:
- agent run은 invoke_agent {gen_ai.agent.name}이 됨(에이전트 이름 채워짐)
- running tool은 execute_tool {gen_ai.tool.name}이 됨(도구 이름 채워짐)
Spec 준수 속성 이름:
- tool_arguments는 gen_ai.tool.call.arguments가 됨
- tool_response는 gen_ai.tool.call.result가 됨
Thinking 토큰 지원: 사용 가능할 때 thinking/추론 토큰을 캡처

Version 4 (deprecated)

멀티모달 입력의 GenAI semantic conventions와 더 잘 정렬되도록 개선된 멀티모달 콘텐츠 처리로 버전 3 위에 구축돼요:

URL 기반 미디어(ImageUrl, AudioUrl, VideoUrl):

이전(v2-3): {"type": "image-url", "url": "..."}
새(v4): {"type": "uri", "modality": "image", "uri": "...", "mime_type": "..."}

인라인 바이너리 콘텐츠(BinaryContent, FilePart):

이전(v2-3): {"type": "binary", "media_type": "...", "content": "..."}
새(v4): {"type": "blob", "modality": "image", "mime_type": "...", "content": "..."}

즉, modality 필드는 OTel spec이 지정한 대로 이미지, 오디오, 비디오 콘텐츠 타입에만 포함돼요. DocumentUrl과 지원되지 않는 미디어 타입은 modality 필드를 생략해요.

Version 5

deferred 도구 호출 처리 개선으로 버전 4 위에 구축돼요:

CallDeferred와 ApprovalRequired 예외는 더 이상 예외 이벤트를 기록하거나 스팬 상태를 ERROR로 설정하지 않아요. deferral은 오류가 아니라 제어 흐름이므로 스팬은 UNSET으로 남아요.

Version 6 (opt-in)

도구 결과에 GenAI semantic conventions가 그것이 지니는 tool_call_response 부분과 짝짓는 메시지 역할을 부여함으로써 버전 5 위에 구축돼요:

이전(v2-5): 도구 결과는 {"role": "user"} 메시지 안의 tool_call_response 부분
새(v6): {"role": "tool"} 메시지로 이동

이것은 도구 반환과 도구 호출에 답하는 재시도에 적용돼요. 아무것도 답하지 않는 재시도 — 출력 검증, validator의 ModelRetry — 는 모델에 도달할 때의 역할인 user에 남아요. 부분이 두 역할에 걸친 요청은 하나의 병합 메시지가 아니라 부분 순서대로 연속 메시지로 방출돼요.

OpenTelemetry Semantic Conventions는 여전히 실험적이며 바뀔 가능성이 높다는 점을 주의하세요.

Setting OpenTelemetry SDK providers

기본적으로 전역 TracerProvider가 사용돼요. 그것은 logfire.configure()가 자동으로 설정해요. OpenTelemetry Python SDK의 set_tracer_provider 함수로도 설정할 수 있어요. InstrumentationSettings로 커스텀 프로바이더를 설정할 수 있어요.

instrumentation_settings_providers.py

from opentelemetry.sdk.trace import TracerProvider

from pydantic_ai import Agent, InstrumentationSettings
from pydantic_ai.capabilities import Instrumentation

instrumentation_settings = InstrumentationSettings(
    tracer_provider=TracerProvider(),
)

agent = Agent('openai:gpt-5.2', capabilities=[Instrumentation(settings=instrumentation_settings)])
# or to instrument all agents:
Agent.instrument_all(instrumentation_settings)

Excluding binary content

include_binary_content=False이면 Pydantic AI는 사용자 프롬프트, 모델 응답, 도구 반환, 에이전트 출력, 출력 함수 인자, 실행·도구 deferral 메타데이터에 대한 텔레메트리에서 이미지, 오디오, 문서를 포함한 바이너리 파일 데이터를 제외해요. 미디어 타입은 모든 곳에 계속 기록돼요. 값이 메시지 부분보다 파일로 기록될 때는 벤더 메타데이터와 식별자도 기록되며, Pydantic AI는 설정하지 않으면 콘텐츠에서 식별자를 파생해요.

바이너리 콘텐츠는 dict, list, ToolReturn 안에서 발견되지만, 자체 타입 안에서는 발견되지 않아요. 당신이 정의한 모델이나 dataclass의 필드로 보관된 BinaryContent는 여전히 전체로 기록돼요.

excluding_binary_content.py

from pydantic_ai import Agent, InstrumentationSettings
from pydantic_ai.capabilities import Instrumentation

instrumentation_settings = InstrumentationSettings(include_binary_content=False)

agent = Agent('openai:gpt-5.2', capabilities=[Instrumentation(settings=instrumentation_settings)])
# or to instrument all agents:
Agent.instrument_all(instrumentation_settings)

Excluding prompts and completions

개인정보 보호와 보안 이유로, 관찰 가능성 플랫폼에서 민감한 사용자 데이터나 독점 프롬프트를 노출하지 않고 에이전트의 동작과 성능을 모니터링하고 싶을 수 있어요. Pydantic AI는 디버깅과 모니터링에 필요한 구조 정보를 보존하면서 텔레메트리에서 실제 콘텐츠를 제외하게 해요.

include_content=False가 설정되면 Pydantic AI는 사용자 프롬프트와 모델 완성, 도구 호출 인자와 응답, 기타 메시지 콘텐츠를 포함한 민감한 콘텐츠를 텔레메트리에서 제외해요. 에이전트 실행 및 도구 스팬에 기록된 예외는 메시지와 스택 트레이스가 그 콘텐츠를 인용할 수 있으므로 타입만 유지해요.

excluding_sensitive_content.py

from pydantic_ai import Agent
from pydantic_ai.capabilities import Instrumentation
from pydantic_ai.models.instrumented import InstrumentationSettings

instrumentation_settings = InstrumentationSettings(include_content=False)

agent = Agent('openai:gpt-5.2', capabilities=[Instrumentation(settings=instrumentation_settings)])
# or to instrument all agents:
Agent.instrument_all(instrumentation_settings)

이 설정은 규정 준수 요구사항이나 데이터 민감성 우려로 관찰 가능성 플랫폼에 보내는 콘텐츠를 제한해야 하는 프로덕션 환경에서 특히 유용해요.

Excluding model request parameters

기본적으로 각 모델 요청 스팬은 출력 구성과 모든 도구 정의를 포함한 전체 ModelRequestParameters를 직렬화하는 model_request_parameters 속성을 지녀요. 큰 출력 스키마를 지니는 도구(예: 일부 MCP 툴셋)는 이 속성을 스팬 export에 부담을 주고 메모리 사용을 부풀릴 만큼 크게 만들 수 있어요. include_model_request_parameters=False를 설정하면 완전히 생략해요:

excluding_model_request_parameters.py

from pydantic_ai import Agent
from pydantic_ai.capabilities import Instrumentation
from pydantic_ai.models.instrumented import InstrumentationSettings

instrumentation_settings = InstrumentationSettings(include_model_request_parameters=False)

agent = Agent('openai:gpt-5.2', capabilities=[Instrumentation(settings=instrumentation_settings)])
# or to instrument all agents:
Agent.instrument_all(instrumentation_settings)

gen_ai.tool.definitions 속성(도구 이름, 설명, 파라미터)은 이 설정과 무관하게 방출되므로, 사용 가능한 도구를 그것에서 읽는 관찰 가능성 플랫폼은 영향받지 않아요.

Adding Custom Metadata

에이전트의 metadata 파라미터를 사용해 에이전트의 스팬에 추가 데이터를 붙일 수 있어요. 계측이 활성화되면 계산된 메타데이터가 metadata 속성 아래 에이전트 스팬에 기록돼요. 자세한 내용과 사용법은 agents 가이드의 usage and metadata 예시를 참고하세요.

계측이 구성될 때까지, 프로세스의 첫 에이전트 실행은 실행을 설명하고 여기를 가리키는 짧은 배너를 stderr에 인쇄해요. 그것은 읽을 사람이 있을 때만 표시돼요. stderr가 터미널일 때, 또는 코딩 에이전트가 프로세스를 실행하고 그것이 쓰는 것을 다시 읽을 때. 계측이 구성되거나, pytest 아래이거나, CI가 어떤 값으로든 설정되면 절대 표시되지 않아요. 완전히 끄려면 환경에서 PYDANTIC_AI_NO_BANNER를 어떤 값으로든 설정하거나, 첫 에이전트 실행 전에 pydantic_ai.BANNER_ENABLED = False를 설정하세요.

코딩 에이전트는 그것을 위해 설정한 환경 변수로 인식돼요. 그 목록은 best-effort이며 항상 뒤처질 것이므로, 인식하지 못하는 harness — Pydantic AI 위에 구축된 것 포함 — 는 그 값에 스스로 이름을 넣어 AI_AGENT(또는 AGENT)를 설정해 같은 방식으로 취급되게 할 수 있어요.

더 알아보기 (Learn more)

pydantic-ai 문서

Pydantic Logfire Debugging and Monitoring

Pydantic Logfire Debugging and Monitoring

본문

Pydantic Logfire

Using Logfire

Debugging

Monitoring Performance

Monitoring HTTP Requests

Using OpenTelemetry

Logfire with an alternative OTel backend

OTel without Logfire

Alternative Observability backends

Advanced usage

Emitted metrics

Aggregated usage attribute names

Configuring data format

Version 2 (deprecated)

Version 3 (deprecated)

Version 4 (deprecated)

Version 5

Version 6 (opt-in)

Setting OpenTelemetry SDK providers

Excluding binary content

Excluding prompts and completions

Excluding model request parameters

Adding Custom Metadata

The first-run banner

더 알아보기 (Learn more)