Skip to content

트레이싱 SDK (potato_trace)

가벼운 potato_trace SDK로 어떤 에이전트든 계측하여 그 실행을 Potato로 캡처해 평가하세요. 함수에 @traceable을 붙이면(동기·비동기 모두) 중첩된 실행까지 캡처되어 Potato의 수집 webhook으로 전송되며, OpenTelemetry 내보내기도 선택할 수 있습니다.

potato_trace는 에이전트의 실행을 캡처해 평가를 위해 Potato로 보내는 가벼운 SDK입니다. Potato가 런타임 경로에 자리하므로, 오프라인 덤프를 가져오는 것에 그치지 않고 실제 실행을 일어나는 그대로 평가할 수 있습니다. 의존성이 가볍고(표준 라이브러리와 전송 시점의 requests) 최상위 패키지이므로, 임포트해도 웹 프레임워크가 딸려 오지 않습니다.

빠른 시작

python
import potato_trace
 
potato_trace.configure(
    potato_url="http://localhost:8000",   # or env POTATO_TRACE_URL
    api_key="",                            # or env POTATO_TRACE_API_KEY
    project_name="my-agent",
)
 
@potato_trace.traceable(run_type="tool")
def search(query):
    return run_search(query)
 
@potato_trace.traceable(run_type="llm")
def summarize(text):
    potato_trace.add_metadata(prompt_tokens=120, completion_tokens=40)
    return call_llm(text)
 
@potato_trace.traceable            # the outermost call is the trace root
def agent(task):
    return summarize(search(task))
 
agent("weather in NYC")
potato_trace.flush()               # ensure sends finish before a short script exits

중첩된 @traceable 호출은 실행 트리를 이룹니다. 루트가 반환되면 트리 전체가 백그라운드 스레드에서 /api/traces/webhook으로 POST됩니다(트레이싱이 에이전트를 멈춰 세우거나 중단시키는 일은 없습니다). potato_url을 구성하지 않으면 트레이싱은 아무 일도 하지 않고 안전하게 넘어갑니다.

API

심볼용도
configure(potato_url=, api_key=, project_name=)전역 클라이언트를 설정합니다
@traceable / @traceable(run_type=, name=, tags=)함수를 트레이싱합니다(동기 또는 비동기). run_type: chain(기본값), llm, tool, retriever
trace(name, run_type=...)컨텍스트 매니저 형태: with trace("step"): ...
set_outputs({...}) / add_metadata(**kw)현재 실행에 출력 / 토큰 사용량을 붙입니다
flush(timeout=30)대기 중인 백그라운드 전송이 끝날 때까지 기다립니다

OpenTelemetry 연동(선택)

스택이 OpenTelemetry 스팬(GenAI 시맨틱 컨벤션)을 내보낸다면 Potato로 곧바로 내보낼 수 있습니다. opentelemetry-sdk는 선택적 extra입니다.

python
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from potato_trace.otel_exporter import build_exporter
 
provider = TracerProvider()
provider.add_span_processor(BatchSpanProcessor(build_exporter(project_name="my-agent")))

트레이스 수신하기

Potato 쪽에서는 webhook이 실행을 받아들이도록 트레이스 수집을 활성화하세요.

yaml
trace_ingestion:
  enabled: true
  api_key: ""    # set a key in production; the SDK sends it as a Bearer token

캡처된 트레이스는 항목이 되어, 평가하거나 자동화 규칙으로 라우팅하거나 데이터셋으로 큐레이션할 수 있습니다.

관련 항목