Controlling Tracing

Enable or disable tracing at the global and agent level

Peargent provides flexible control over tracing behavior. You can enable tracing globally with enable_tracing() and selectively opt agents in or out using the tracing parameter.

How Tracing Works

The interaction between enable_tracing() and the tracing parameter determines whether an agent is traced:

Global (`enable_tracing()`)	Agent/Pool (`tracing=`)	Result	Explanation
❌ Not called	Not specified	❌ No tracing	Default: tracing disabled
❌ Not called	`tracing=True`	❌ No tracing	Agent wants tracing but no global tracer configured
✅ Called	Not specified	✅ Traced	Agent inherits global tracing
✅ Called	`tracing=True`	✅ Traced	Agent explicitly opts in
✅ Called	`tracing=False`	❌ No tracing	Agent explicitly opts out
✅ Called (`enabled=False`)	`tracing=True`	❌ No tracing	Global `enabled=False` takes precedence

Global Control

Use enable_tracing() to control the master switch.

from peargent.observability import enable_tracing 

# Enable globally (default)
tracer = enable_tracing() 

# Disable globally (master switch OFF)
tracer = enable_tracing(enabled=False)

Important: If enabled=False globally, NO agents will be traced, even if they explicitly set tracing=True.

Agent-Level Control

You can opt specific agents in or out of tracing:

# Opt-in (redundant if global is enabled, but good for clarity)
agent1 = create_agent(..., tracing=True) 

# Opt-out (skip tracing for this agent)
agent2 = create_agent(..., tracing=False)

Pool-Level Control

Pools also support the tracing parameter, which applies to all agents in the pool unless they have their own explicit setting.

# Enable tracing for the pool
pool = create_pool(agents=[a1, a2], tracing=True) 

# Disable tracing for the pool
pool = create_pool(agents=[a1, a2], tracing=False)

Note: An agent's explicit tracing setting always overrides the pool's setting.

What's Next?

Tracing Storage Configure persistent storage for your traces using SQLite, PostgreSQL, or Redis.