Skip to content

Stealth browser automation for AI agents over MCP and the Chrome DevTools Protocol: navigation, network hooks, DOM extraction, and pixel-accurate UI cloning.

fix(logging): suppress stderr noise unless debug is enabled

Vibhek Sonica885ff4597b
diff --git a/src/browser_manager.py b/src/browser_manager.py
index 112f78a..c465af2 100644
--- a/src/browser_manager.py
+++ b/src/browser_manager.py
@@ -193,7 +193,11 @@ class BrowserManager:
width=options.viewport_width,
height=options.viewport_height
)
- print(f"[DEBUG] Set viewport to {options.viewport_width}x{options.viewport_height}", file=sys.stderr)
+ debug_logger.log_info(
+ "browser_manager",
+ "spawn_browser",
+ f"Set viewport to {options.viewport_width}x{options.viewport_height}",
+ )
applied_timezone_id = await self._apply_timezone_override(
tab=tab,
diff --git a/src/debug_logger.py b/src/debug_logger.py
index efe24ce..ae0f668 100644
--- a/src/debug_logger.py
+++ b/src/debug_logger.py
@@ -39,6 +39,21 @@ class DebugLogger:
self._lock_acquired_time = 0
self._seen_errors: set = set()
+ def _emit_stderr(self, message: str, force: bool = False):
+ """
+ Emit a debug line to stderr only when logging is enabled unless forced.
+
+ Args:
+ message (str): Message to emit.
+ force (bool): Whether to emit regardless of current debug state.
+ """
+ if not force and not self._enabled:
+ return
+ try:
+ print(message, file=sys.stderr)
+ except Exception:
+ pass
+
def log_error(self, component: str, method: str, error: Exception, context: Optional[Dict[str, Any]] = None):
"""
Log an error with full context.
@@ -72,7 +87,7 @@ class DebugLogger:
}
self._errors.append(error_entry)
self._stats[f'{component}.{method}.errors'] += 1
- print(f"[DEBUG ERROR] {component}.{method}: {error}", file=sys.stderr)
+ self._emit_stderr(f"[DEBUG ERROR] {component}.{method}: {error}")
def log_warning(self, component: str, method: str, message: str, context: Optional[Dict[str, Any]] = None):
"""
@@ -97,7 +112,7 @@ class DebugLogger:
}
self._warnings.append(warning_entry)
self._stats[f'{component}.{method}.warnings'] += 1
- print(f"[DEBUG WARN] {component}.{method}: {message}", file=sys.stderr)
+ self._emit_stderr(f"[DEBUG WARN] {component}.{method}: {message}")
def log_info(self, component: str, method: str, message: str, data: Optional[Any] = None):
"""
@@ -122,9 +137,9 @@ class DebugLogger:
}
self._info.append(info_entry)
self._stats[f'{component}.{method}.calls'] += 1
- print(f"[DEBUG INFO] {component}.{method}: {message}", file=sys.stderr)
+ self._emit_stderr(f"[DEBUG INFO] {component}.{method}: {message}")
if data:
- print(f" Data: {data}", file=sys.stderr)
+ self._emit_stderr(f" Data: {data}")
def get_debug_view(self) -> Dict[str, Any]:
"""
@@ -243,13 +258,13 @@ class DebugLogger:
self._warnings.clear()
self._info.clear()
self._stats.clear()
- print("[DEBUG] Debug logs cleared", file=sys.stderr)
+ self._emit_stderr("[DEBUG] Debug logs cleared")
finally:
self._lock.release()
else:
- print("[DEBUG] Failed to clear logs - timeout acquiring lock", file=sys.stderr)
+ self._emit_stderr("[DEBUG] Failed to clear logs - timeout acquiring lock")
except Exception as e:
- print(f"[DEBUG] Error clearing logs: {e}", file=sys.stderr)
+ self._emit_stderr(f"[DEBUG] Error clearing logs: {e}")
def clear_debug_view_safe(self):
"""
@@ -262,7 +277,7 @@ class DebugLogger:
self._warnings = []
self._info = []
self._stats = defaultdict(int)
- print("[DEBUG] Debug logs force-cleared (lock bypass)", file=sys.stderr)
+ self._emit_stderr("[DEBUG] Debug logs force-cleared (lock bypass)")
def enable(self):
"""
@@ -272,7 +287,7 @@ class DebugLogger:
self._enabled (bool): Set to True.
"""
self._enabled = True
- print("[DEBUG] Debug logging enabled", file=sys.stderr)
+ self._emit_stderr("[DEBUG] Debug logging enabled", force=True)
def disable(self):
"""
@@ -281,8 +296,8 @@ class DebugLogger:
Variables:
self._enabled (bool): Set to False.
"""
+ self._emit_stderr("[DEBUG] Debug logging disabled")
self._enabled = False
- print("[DEBUG] Debug logging disabled", file=sys.stderr)
def get_lock_status(self) -> Dict[str, Any]:
"""Get current lock status for debugging."""
@@ -328,18 +343,18 @@ class DebugLogger:
"""
import time
try:
- print(f"[DEBUG] export_debug_logs attempting lock acquisition...", file=sys.stderr)
+ self._emit_stderr("[DEBUG] export_debug_logs attempting lock acquisition...")
current_status = self.get_lock_status()
- print(f"[DEBUG] Current lock status: {current_status}", file=sys.stderr)
+ self._emit_stderr(f"[DEBUG] Current lock status: {current_status}")
acquired = self._lock.acquire(timeout=5.0)
if not acquired:
- print("[DEBUG] Lock timeout - falling back to lock-free export", file=sys.stderr)
+ self._emit_stderr("[DEBUG] Lock timeout - falling back to lock-free export")
return self._export_lockfree(filepath, max_errors, max_warnings, max_info, format)
self._lock_owner = "export_debug_logs"
self._lock_acquired_time = time.time()
- print("[DEBUG] Lock acquired by export_debug_logs", file=sys.stderr)
+ self._emit_stderr("[DEBUG] Lock acquired by export_debug_logs")
try:
debug_data = self.get_debug_view_paginated(
@@ -351,9 +366,9 @@ class DebugLogger:
self._lock_owner = "none"
self._lock_acquired_time = 0
self._lock.release()
- print("[DEBUG] Lock released by export_debug_logs", file=sys.stderr)
+ self._emit_stderr("[DEBUG] Lock released by export_debug_logs")
except Exception as e:
- print(f"[DEBUG] Exception in export: {e}", file=sys.stderr)
+ self._emit_stderr(f"[DEBUG] Exception in export: {e}")
return self._export_lockfree(filepath, max_errors, max_warnings, max_info, format)
if format == "auto":
@@ -427,10 +442,12 @@ class DebugLogger:
pickle.dump(debug_data, f, protocol=pickle.HIGHEST_PROTOCOL)
file_size = os.path.getsize(filepath)
- print(f"[DEBUG] Exported {debug_data['summary']['returned_errors']} errors, "
- f"{debug_data['summary']['returned_warnings']} warnings, "
- f"{debug_data['summary']['returned_info']} info logs to {filepath} "
- f"({file_size} bytes, gzip-pickle format)", file=sys.stderr)
+ self._emit_stderr(
+ f"[DEBUG] Exported {debug_data['summary']['returned_errors']} errors, "
+ f"{debug_data['summary']['returned_warnings']} warnings, "
+ f"{debug_data['summary']['returned_info']} info logs to {filepath} "
+ f"({file_size} bytes, gzip-pickle format)"
+ )
return filepath
def _export_pickle(self, debug_data: Dict[str, Any], filepath: str) -> str:
@@ -442,10 +459,12 @@ class DebugLogger:
pickle.dump(debug_data, f, protocol=pickle.HIGHEST_PROTOCOL)
file_size = os.path.getsize(filepath)
- print(f"[DEBUG] Exported {debug_data['summary']['returned_errors']} errors, "
- f"{debug_data['summary']['returned_warnings']} warnings, "
- f"{debug_data['summary']['returned_info']} info logs to {filepath} "
- f"({file_size} bytes, pickle format)", file=sys.stderr)
+ self._emit_stderr(
+ f"[DEBUG] Exported {debug_data['summary']['returned_errors']} errors, "
+ f"{debug_data['summary']['returned_warnings']} warnings, "
+ f"{debug_data['summary']['returned_info']} info logs to {filepath} "
+ f"({file_size} bytes, pickle format)"
+ )
return filepath
def _export_json(self, debug_data: Dict[str, Any], filepath: str) -> str:
@@ -454,11 +473,13 @@ class DebugLogger:
json.dump(debug_data, f, separators=(',', ':'), default=str)
file_size = os.path.getsize(filepath)
- print(f"[DEBUG] Exported {debug_data['summary']['returned_errors']} errors, "
- f"{debug_data['summary']['returned_warnings']} warnings, "
- f"{debug_data['summary']['returned_info']} info logs to {filepath} "
- f"({file_size} bytes, JSON format)", file=sys.stderr)
+ self._emit_stderr(
+ f"[DEBUG] Exported {debug_data['summary']['returned_errors']} errors, "
+ f"{debug_data['summary']['returned_warnings']} warnings, "
+ f"{debug_data['summary']['returned_info']} info logs to {filepath} "
+ f"({file_size} bytes, JSON format)"
+ )
return filepath
-debug_logger = DebugLogger()
\ No newline at end of file
+debug_logger = DebugLogger()
diff --git a/src/network_interceptor.py b/src/network_interceptor.py
index 01c9d0f..918d575 100644
--- a/src/network_interceptor.py
+++ b/src/network_interceptor.py
@@ -3,7 +3,6 @@
import asyncio
import base64
import json
-import sys
from datetime import datetime
from pathlib import Path
from typing import Any, Dict, List, Optional
@@ -11,6 +10,7 @@ from typing import Any, Dict, List, Optional
import nodriver as uc
from nodriver import Tab
+from debug_logger import debug_logger
from models import NetworkRequest, NetworkResponse
@@ -50,16 +50,31 @@ class NetworkInterceptor:
if resource_type.lower() in resource_patterns:
url_patterns.extend(resource_patterns[resource_type.lower()])
- print(f"[DEBUG] Added URL patterns for {resource_type}: {resource_patterns[resource_type.lower()]}", file=sys.stderr)
+ debug_logger.log_info(
+ "network_interceptor",
+ "setup_interception",
+ f"Added URL patterns for {resource_type}",
+ resource_patterns[resource_type.lower()],
+ )
else:
# Assume it's already a URL pattern
url_patterns.append(resource_type)
- print(f"[DEBUG] Added custom URL pattern: {resource_type}", file=sys.stderr)
+ debug_logger.log_info(
+ "network_interceptor",
+ "setup_interception",
+ "Added custom URL pattern",
+ resource_type,
+ )
# Use network.set_blocked_ur_ls to block the URL patterns
if url_patterns:
await tab.send(uc.cdp.network.set_blocked_ur_ls(urls=url_patterns))
- print(f"[DEBUG] Blocked {len(url_patterns)} URL patterns: {url_patterns}", file=sys.stderr)
+ debug_logger.log_info(
+ "network_interceptor",
+ "setup_interception",
+ f"Blocked {len(url_patterns)} URL patterns",
+ url_patterns,
+ )
tab.add_handler(
uc.cdp.network.RequestWillBeSent,
@@ -74,7 +89,7 @@ class NetworkInterceptor:
if instance_id not in self._instance_requests:
self._instance_requests[instance_id] = []
except Exception as e:
- print(f"[DEBUG] Error in setup_interception: {e}", file=sys.stderr)
+ debug_logger.log_error("network_interceptor", "setup_interception", e)
raise Exception(f"Failed to setup network interception: {str(e)}")
async def _on_request(self, event, instance_id: str):
@@ -571,4 +586,4 @@ class NetworkInterceptor:
for req_id in self._instance_requests[instance_id]:
self._requests.pop(req_id, None)
self._responses.pop(req_id, None)
- del self._instance_requests[instance_id]
\ No newline at end of file
+ del self._instance_requests[instance_id]
diff --git a/src/server.py b/src/server.py
index 2b4b6ca..6e99dfc 100644
--- a/src/server.py
+++ b/src/server.py
@@ -51,6 +51,12 @@ def parse_bool_env(name: str, default: bool = False) -> bool:
return default
return value.strip().lower() in {"1", "true", "yes", "on", "enabled"}
+
+DEBUG_LOGGING_ENABLED = (
+ parse_bool_env("STEALTH_BROWSER_DEBUG", default=False)
+ or parse_bool_env("DEBUG", default=False)
+)
+
def is_section_enabled(section: str) -> bool:
"""Check if a tool section is enabled."""
return section not in DISABLED_SECTIONS
@@ -134,6 +140,9 @@ network_interceptor = NetworkInterceptor()
dom_handler = DOMHandler()
cdp_function_executor = CDPFunctionExecutor()
+if DEBUG_LOGGING_ENABLED:
+ debug_logger.enable()
+
@section_tool("browser-management")
async def spawn_browser(
headless: bool = False,
@@ -2783,6 +2792,12 @@ if __name__ == "__main__":
help="Enable only core browser management and element interaction (disable everything else)")
parser.add_argument("--list-sections", action="store_true",
help="List all available tool sections and exit")
+ parser.add_argument(
+ "--debug",
+ action="store_true",
+ default=DEBUG_LOGGING_ENABLED,
+ help="Enable debug logging to stderr",
+ )
parser.add_argument(
"--xpool-safe",
action="store_true",
@@ -2791,6 +2806,9 @@ if __name__ == "__main__":
)
args = parser.parse_args()
+
+ if args.debug and not debug_logger._enabled:
+ debug_logger.enable()
if args.list_sections:
print("Available tool sections:")
@@ -2845,7 +2863,11 @@ if __name__ == "__main__":
apply_disabled_sections()
if DISABLED_SECTIONS:
- print(f"Disabled tool sections: {', '.join(sorted(DISABLED_SECTIONS))}", file=sys.stderr)
+ debug_logger.log_info(
+ "server",
+ "startup",
+ f"Disabled tool sections: {', '.join(sorted(DISABLED_SECTIONS))}",
+ )
if args.transport == "http":
mcp.run(transport="http", host=args.host, port=args.port)