Tracing and Observability

Monitor agent performance, track costs, and debug with comprehensive tracing

Tracing gives you complete visibility into what your agents are doing. Track LLM calls, tool executions, token usage, API costs, and performance metrics in real-time.

| Tracing is fully optional and adds minimal overhead (usually <10ms), making it safe for production.

Why Tracing?

Production AI applications need observability:

• Cost Control - Track token usage and API costs per request
• Performance Monitoring - Measure latency and identify bottlenecks
• Debugging - See exactly what happened when something fails
• Usage Analytics - Understand how agents and tools are being used

Quick Start

Enable tracing in one line:

from peargent import create_agent 
from peargent.observability import enable_tracing 
from peargent.models import openai 

# Enable tracing
tracer = enable_tracing() 

# Create agent with tracing enabled
agent = create_agent(
    name="Assistant",
    description="Helpful assistant",
    persona="You are helpful",
    model=openai("gpt-4o"),
    tracing=True
)

# Run agent - traces are automatically captured
result = agent.run("What is 2+2?")

# View traces
tracer.print_summary()

Output:

TRACE SUMMARY
Total Traces: 1
Total Tokens: 127
Total Cost: $0.000082

What Gets Traced?

Every agent execution creates a Trace containing multiple Spans:

Trace

Represents a full agent execution. Includes:

• ID – Unique identifier
• Agent – Which agent ran
• Tokens & Cost – Total usage and API cost
• Duration – Total time taken

Spans

Individual operations inside a trace:

• LLM Call – Model, tokens, cost, latency
• Tool Execution – Tool name, inputs, outputs, duration
• Agent Logic – Reasoning steps

Storage Options

Peargent supports multiple storage backends including In-Memory (default), SQLite, PostgreSQL, Redis, and File-based.

See Tracing Storage for detailed setup and configuration.

Viewing Traces

List all traces or print a summary:

# List traces
traces = tracer.list_traces() 
for trace in traces:
    print(f"Trace {trace.id}: {trace.total_cost:.6f}")

# Print summary
tracer.print_summary() 

What's Next?

Cost Tracking Learn about model pricing, cost calculation, and optimization strategies.

Tracing Storage Set up SQLite, PostgreSQL, or Redis for persistent trace storage.