Telemetry & Logging
Relevant source files
The following files were used as context for generating this wiki page:
The Telemetry and Logging systems in browser-use provide comprehensive observability into agent behaviors, browser interactions, and system performance. These systems are designed to track execution flow, capture performance metrics, and log detailed interaction data for debugging and product improvement.
Introduction
The telemetry system specifically focuses on product usage metrics and event tracking, such as agent run starts, step-by-step actions, and task completion status. Logging, on the other hand, provides real-time visibility into internal operations, including DOM interactions, LLM response parsing, and browser networking events.
Sources: browser_use/telemetry/service.py, browser_use/agent/service.py:126-128, browser_use/browser/context.py:44-46
Telemetry System Architecture
The telemetry system is centered around the ProductTelemetry class, which captures specific lifecycle events of an AI agent. It utilizes structured data models to ensure consistency across different event types.
Telemetry Lifecycle
Telemetry events are captured at three primary stages of an agent's execution:
- Run Start: Captures the initial task, model names, and environment versions.
- Step Execution: Records every individual step, including the actions taken and any consecutive failures.
- Run End: Logs the final success status, total steps taken, and any errors encountered.
The diagram shows the standard flow of telemetry event capture during an agent's lifecycle.
Sources: browser_use/agent/service.py:348-360, browser_use/agent/service.py:314-322, browser_use/agent/service.py:461-469
Telemetry Event Models
Telemetry data is structured using Pydantic-style models or dataclasses to track specific metadata.
| Event Type | Key Data Fields | Purpose |
|---|---|---|
AgentRunTelemetryEvent | agent_id, task, model_name, version, source | Initial context of the run. |
AgentStepTelemetryEvent | step, actions, consecutive_failures, step_error | Per-step performance and failure tracking. |
AgentEndTelemetryEvent | success, steps, max_steps_reached, errors | Final outcome and duration metrics. |
Sources: browser_use/agent/service.py:349-359, browser_use/agent/service.py:315-321, browser_use/agent/service.py:462-468
Logging Infrastructure
The project uses the standard Python logging module across all major services to provide a technical trail of execution.
Browser & Context Logging
The BrowserContext logs detailed information regarding session initialization, network stabilization, and DOM manipulation. This includes:
- Session Management: Tracking context IDs and session creation.
- Network Events: Logging when the network stabilizes or when timeouts occur during page loads.
- Navigation Handling: Identifying restricted URL access attempts.
# Example of network logging in BrowserContext
logger.debug(f'Network stabilized for {self.config.wait_for_network_idle_page_load_time} seconds')
logger.debug(f'Network timeout after {self.config.maximum_wait_page_load_time}s with {len(pending_requests)} pending requests')
Sources: browser_use/browser/context.py:175, browser_use/browser/context.py:311-314, browser_use/browser/context.py:461
Controller & Action Logging
The Controller logs specific browser actions executed by the agent, providing a human-readable audit trail of "clicks", "inputs", and "navigation".
| Component | Logged Information | Example Message |
|---|---|---|
| Navigation | URL changes and Google searches | 🔍 Searched for "{query}" in Google |
| Interaction | Clicking elements and typing text | ⌨️ Input {text} into index {index} |
| Tab Management | Switching or opening new tabs | 🔄 Switched to tab {page_id} |
Sources: browser_use/controller/service.py:61, browser_use/controller/service.py:101, browser_use/controller/service.py:141
Performance & Token Tracking
The MessageManager and Agent services include specific logic for logging and tracking token consumption and execution time.
Token Usage Logging
The MessageManager logs the token count for each message in the history, which is critical for staying within LLM context limits. If limits are reached, it logs the percentage of content being "cut" to fit the window.
The flow shows how the system monitors and logs token usage adjustments.
Sources: browser_use/agent/message_manager/service.py:193-199, browser_use/agent/message_manager/service.py:236-240
Execution Timing
The project utilizes decorators like @time_execution_async and @time_execution_sync to log the duration of critical methods such as step(), get_state(), and multi_act().
Sources: browser_use/agent/service.py:157, browser_use/browser/context.py:466, browser_use/controller/service.py:382
Summary
The Telemetry and Logging systems provide a dual-layer observability framework. ProductTelemetry handles high-level event tracking for usage analytics, while distributed logging across BrowserContext, Controller, and Agent provides the granular detail required for technical debugging and performance optimization. These systems ensure that every action, from a low-level network request to a high-level agent goal, is accounted for and measurable.