Context Observability & History

Track optimization events and debug context management

from praisonaiagents import Agent

agent = Agent(
    name="observable-agent",
    instructions="Run with full context observability enabled.",
)
agent.start("Trace all context events for this task.")

Context observability provides optimization history tracking, event logging, and debugging tools.

The user debugs a run; context observability logs compaction and overflow events with token savings.

How It Works

Quick Start

1. Process messages and read history

   from praisonaiagents import ContextManager
   
   manager = ContextManager(model="gpt-4o-mini")
   result = manager.process(messages=messages)
   
   for event in manager.get_history():
       print(f"{event['event_type']}: {event['tokens_saved']} saved")
   
2. Inspect via chat commands

   praisonai chat
   > /context history
   > /context show
   

Optimization Events

Event Type	Description
overflow_detected	Context exceeded threshold
auto_compact	Auto-compaction triggered
benefit_check	Compression benefit evaluated
revert	Compression reverted (not beneficial)
cap_outputs	Tool outputs capped
prune_tools	Old tool outputs pruned
sliding_window	Sliding window applied
summarize	Messages summarized
snapshot	Context snapshot taken

OptimizationEvent

@dataclass
class OptimizationEvent:
    timestamp: str              # ISO timestamp
    event_type: str             # Event type
    strategy: str               # Strategy used
    tokens_before: int          # Tokens before
    tokens_after: int           # Tokens after
    tokens_saved: int           # Tokens saved
    messages_affected: int      # Messages changed
    details: Dict[str, Any]     # Additional info

Sinks may see a result with emergency_truncated: True even when the configured strategy raised. This is the failure-fallback path from PraisonAI PR #4242 — the strategy failed, so the manager fell back to emergency truncation to keep the request inside the model window. Treat it as expected, not an error state, and distinguish it from a normal strategy-driven optimization event (where emergency_truncated is absent). See Context Strategies → Failure Fallback.

History Tracking

# Get all history
history = manager.get_history()

# Filter by event type
compactions = [e for e in history if e['event_type'] == 'auto_compact']

# Get total tokens saved
total_saved = sum(e['tokens_saved'] for e in history)

CLI Commands

# Show optimization history
praisonai chat
> /context history

# Output:
# Time                     Event                Tokens       Saved
# ----------------------------------------------------------------------
# 2024-01-01T12:00:00      overflow_detected       45,000          -
# 2024-01-01T12:00:01      auto_compact           45,000     -15,000
# 2024-01-01T12:00:01      benefit_check          30,000          -

Context Stats

stats = manager.get_stats()

print(f"Model: {stats['model']}")
print(f"Utilization: {stats['utilization']*100:.1f}%")
print(f"History events: {stats['history_events']}")
print(f"Warnings: {stats['warnings']}")

CLI Stats Commands

# Show summary
> /context show

# Show token ledger
> /context stats

# Show budget allocation
> /context budget

Monitoring Integration

Events are included in monitor snapshots:

config = ManagerConfig(
    monitor_enabled=True,
    monitor_format="json",
)

# JSON snapshots include:
# - optimization_history
# - estimation_metrics
# - warnings

Best Practices

Review history after incidents

Check which optimisations ran when answers suddenly degrade mid-session.

Watch for reverts

A reverted compression means the strategy did not help — try retrieval or summarisation instead.

Track utilisation trends

Rising utilisation across turns signals you need tighter budgets or earlier compaction.

Act on warnings early

Treat overflow warnings as action items, not noise — fix before the API rejects the request.

Related

Context Monitor

Real-time context snapshots

Context Strategies

Optimisation strategies and defaults

Gateway Tracing Hook

Emit OpenTelemetry spans across each gateway pipeline stage