Skip to content
Эта страница пока недоступна на вашем языке. Показана английская версия.

Tracing SDK (potato_trace)

Instrument any agent with the lightweight potato_trace SDK to capture its runs into Potato for evaluation. Decorate functions with @traceable (sync or async) and nested runs are captured and sent to Potato's ingestion webhook, with optional OpenTelemetry export.

potato_trace is a lightweight SDK that captures your agent's runs and sends them to Potato for evaluation. Potato sits in the runtime path, so you evaluate real runs as they happen instead of only importing offline dumps. It is dependency-light (standard library plus requests at send time) and a top-level package, so importing it never pulls in a web framework.

Quick start

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

Nested @traceable calls form a run tree; when the root returns, the whole tree is POSTed to /api/traces/webhook in a background thread (tracing never blocks or crashes your agent). If no potato_url is configured, tracing is a safe no-op.

API

SymbolPurpose
configure(potato_url=, api_key=, project_name=)Set the global client
@traceable / @traceable(run_type=, name=, tags=)Trace a function (sync or async); run_type: chain (default), llm, tool, retriever
trace(name, run_type=...)Context-manager form: with trace("step"): ...
set_outputs({...}) / add_metadata(**kw)Attach outputs / token usage to the current run
flush(timeout=30)Wait for pending background sends

OpenTelemetry interop (optional)

If your stack emits OpenTelemetry spans (GenAI semantic conventions), export them to Potato directly. opentelemetry-sdk is an optional 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")))

Receiving the traces

On the Potato side, enable trace ingestion so the webhook accepts the runs:

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

Captured traces become items you can evaluate, route with automation rules, or curate into datasets.