Tracing

Mobilerun provides multiple monitoring capabilities:

LLM Tracing - Real-time execution tracing via Arize Phoenix or Langfuse
Trajectory Recording - Local screenshots and UI state for debugging

Quick Reference

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

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

LLM Tracing

Mobilerun 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 Mobilerun: Via CLI:

mobilerun run "Open settings" --tracing

Via config.yaml:

tracing:
  enabled: true

Via code:

from mobilerun import MobileAgent, MobileConfig

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

agent = MobileAgent(goal="Open settings", config=config)
await 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, FastAgent)
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://0.0.0.0:6006)
export phoenix_url=http://localhost:6006

# Project name for organizing traces
export phoenix_project_name=my_mobilerun_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:

Cloud: Sign up at cloud.langfuse.com
Self-hosted: Deploy using Langfuse docs

2. Configure Mobilerun: 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: user@example.com  # Optional: track by user
  langfuse_session_id: ""              # Optional: custom session ID

Via code:

from mobilerun import MobileAgent, MobileConfig, TracingConfig

config = MobileConfig(
    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="user@example.com",
    )
)

agent = MobileAgent(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 or Langfuse), trajectories stay on your machine.

Recording Levels

Level	What’s Saved	When to Use
`none` (default)	Nothing	Production use, saves disk space
`step`	Screenshot + state per agent step	General debugging, recommended for most use cases
`action`	Screenshot + state per atomic action	Detailed debugging, captures every tap/swipe/type

Note: action level generates significantly more files than step level.

Enable Recording

Via CLI:

mobilerun run "Open settings" --save-trajectory step

Via config.yaml:

logging:
  save_trajectory: step  # none | step | action

Via code:

from mobilerun import MobileAgent, MobileConfig

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

agent = MobileAgent(goal="Open settings", config=config)
await 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

Configuration System - Configure tracing and telemetry settings
Events and Workflows - Build custom monitoring integrations
CLI Usage - Command-line flags for monitoring

Introduction

Features

Guides

Concepts

SDK Reference

Quick Reference

LLM Tracing

Arize Phoenix Tracing

Setup

Phoenix Configuration

Langfuse Tracing

Setup

Trajectory Recording

Recording Levels

Enable Recording

Output Location

​Quick Reference

​LLM Tracing

​Arize Phoenix Tracing

​Setup

​Phoenix Configuration

​Langfuse Tracing

​Setup

​Trajectory Recording

​Recording Levels

​Enable Recording

​Output Location

​Related Documentation

Quick Reference

LLM Tracing

Arize Phoenix Tracing

Setup

Phoenix Configuration

Langfuse Tracing

Setup

Trajectory Recording

Recording Levels

Enable Recording

Output Location

Related Documentation