Skip to main content
Droidrun provides two monitoring capabilities:
  1. Arize Phoenix Tracing - Real-time LLM and agent execution tracing
  2. Trajectory Recording - Local screenshots and UI state for debugging

​
Quick Reference

# Enable Phoenix tracing
droidrun run "task" --tracing

# Enable trajectory recording
droidrun run "task" --save-trajectory step

​
Arize Phoenix Tracing

Phoenix provides real-time tracing of LLM calls, agent execution, and tool invocations. Use it to debug agent behavior, monitor token usage, and analyze execution flow.

​
Setup

1. Install Phoenix: 
uv pip install arize-phoenix
2. Start Phoenix server: 
phoenix serve
The server starts at http://localhost:6006 and provides a web UI for viewing traces. 3. Enable tracing in Droidrun: Via CLI: 
droidrun run "Open settings" --tracing
Via config.yaml: 
tracing:
  enabled: true
Via code: 
from droidrun import DroidAgent
from droidrun.config_manager.config_manager import DroidrunConfig

config = DroidrunConfig()
config.tracing.enabled = True

agent = DroidAgent(goal="Open settings", config=config)
agent.run()
4. View traces: Navigate to http://localhost:6006 to see:
  • LLM calls with prompts, responses, and token counts
  • Agent workflow execution (Manager, Executor, CodeAct)
  • Tool invocations and their results
  • Execution timings and errors
For more on using Phoenix, see the Arize Phoenix documentation.

​
Configuration

Set environment variables to customize Phoenix: 
# Custom Phoenix server URL (default: http://127.0.0.1:6006)
export phoenix_url=http://localhost:6006

# Project name for organizing traces
export phoenix_project_name=my_droidrun_project
Environment variable names are lowercase: phoenix_url and phoenix_project_name.

​
Trajectory Recording

Trajectory recording saves screenshots and UI state locally for offline debugging and analysis. Unlike telemetry (sent to PostHog) and tracing (sent to Phoenix), trajectories stay on your machine.

​
Recording Levels

LevelWhat’s SavedWhen to Use
none (default)NothingProduction use, saves disk space
stepScreenshot + state per agent stepGeneral debugging, recommended for most use cases
actionScreenshot + state per atomic actionDetailed debugging, captures every tap/swipe/type
Note: action level generates significantly more files than step level.

​
Enable Recording

Via CLI: 
droidrun run "Open settings" --save-trajectory step
Via config.yaml: 
logging:
  save_trajectory: step  # none | step | action
Via code: 
from droidrun import DroidAgent
from droidrun.config_manager.config_manager import DroidrunConfig

config = DroidrunConfig()
config.logging.save_trajectory = "action"

agent = DroidAgent(goal="Open settings", config=config)
agent.run()

​
Output Location

Trajectories are saved to trajectories/ in your working directory: 
trajectories/
└── 2025-10-17_14-30-45_open_settings/
    ├── step_000_screenshot.png
    ├── step_000_state.json
    ├── step_001_screenshot.png
    └── step_001_state.json
Each trajectory folder contains:
  • Screenshots - PNG images of the device screen at each step/action
  • State files - JSON files with:
    • UI accessibility tree (element hierarchy with IDs, text, bounds)
    • Action executed (e.g., click(5), type("hello", 3))
    • Agent reasoning and step number
    • Device state (current app package, activity)
Use these files to:
  • Debug why the agent made specific decisions
  • Replay failed executions
  • Analyze UI element detection issues
  • Build training datasets for agent improvement
⌘I