Skip to main content
Droidrun provides multiple monitoring capabilities:
  1. LLM Tracing - Real-time execution tracing via Arize Phoenix or Langfuse
  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

​
LLM Tracing

Droidrun supports two tracing providers for real-time monitoring of LLM calls, agent execution, and tool invocations:
  • Arize Phoenix (default) - Open-source observability platform
  • Langfuse - LLM engineering platform with cloud and self-hosted options
Use tracing to debug agent behavior, monitor token usage, and analyze execution flow.

​
Arize Phoenix Tracing

​
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, 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. Phoenix 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.

​
Langfuse Tracing

Langfuse provides LLM observability with features like session tracking, user analytics, and cost monitoring. Setup 1. Get Langfuse credentials: 2. Configure Droidrun: Via environment variables: 
export LANGFUSE_SECRET_KEY=sk-lf-...
export LANGFUSE_PUBLIC_KEY=pk-lf-...
export LANGFUSE_HOST=https://cloud.langfuse.com
Via config.yaml: 
tracing:
  enabled: true
  provider: langfuse
  langfuse_secret_key: sk-lf-...
  langfuse_public_key: pk-lf-...
  langfuse_host: https://cloud.langfuse.com
  langfuse_user_id: [email protected]  # Optional: track by user
  langfuse_session_id: ""              # Optional: custom session ID
Via code: 
from droidrun import DroidAgent, DroidrunConfig, TracingConfig

config = DroidrunConfig(
    tracing=TracingConfig(
        enabled=True,
        provider="langfuse",
        langfuse_secret_key="sk-lf-...",
        langfuse_public_key="pk-lf-...",
        langfuse_host="https://cloud.langfuse.com",
        langfuse_user_id="[email protected]",
    )
)

agent = DroidAgent(goal="Open settings", config=config)
await agent.run()
3. View traces: Navigate to your Langfuse dashboard to see:
  • LLM calls with prompts, completions, and token usage
  • Agent execution traces and nested workflows
  • Session-based analytics and cost tracking
  • User-level metrics (if langfuse_user_id is set)
For more on using Langfuse, see the Langfuse documentation.

​
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, 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