Verbose logging in headless Chromium is essential for troubleshooting rendering issues, script errors, network problems, and other browser-related debugging tasks. This guide covers multiple methods to enable comprehensive logging.
Command-Line Logging Options
Direct Command Line
Run Chromium directly with verbose logging enabled:
# Basic verbose logging
chromium-browser --headless --enable-logging --v=1 --no-sandbox
# Extended logging with network and console logs
chromium-browser --headless \
--enable-logging \
--v=2 \
--log-level=0 \
--enable-logging=stderr \
--vmodule="*/chrome/*=1" \
--no-sandbox
Advanced Logging Flags
# Network request logging
chromium-browser --headless \
--enable-logging \
--log-net-log=/tmp/net-log.json \
--net-log-capture-mode=IncludeCookiesAndCredentials
# DevTools protocol logging
chromium-browser --headless \
--enable-logging \
--enable-devtools-experiments \
--remote-debugging-port=9222 \
--devtools-flags="--enable-logging"
Selenium WebDriver Configuration
Python with Selenium
from selenium import webdriver
from selenium.webdriver.chrome.options import Options
from selenium.webdriver.chrome.service import Service
from selenium.webdriver.common.desired_capabilities import DesiredCapabilities
import logging
# Configure logging
logging.basicConfig(level=logging.DEBUG)
# Chrome options with verbose logging
chrome_options = Options()
chrome_options.add_argument("--headless")
chrome_options.add_argument("--no-sandbox")
chrome_options.add_argument("--disable-dev-shm-usage")
chrome_options.add_argument("--enable-logging")
chrome_options.add_argument("--v=1")
chrome_options.add_argument("--log-level=0")
chrome_options.add_argument("--enable-logging=stderr")
# Enable performance and network logs
caps = DesiredCapabilities.CHROME
caps['goog:loggingPrefs'] = {
'browser': 'ALL',
'driver': 'ALL',
'performance': 'ALL'
}
# Service configuration
service = Service(executable_path="/path/to/chromedriver")
service.log_path = "./chromedriver.log"
# Initialize driver
driver = webdriver.Chrome(
service=service,
options=chrome_options,
desired_capabilities=caps
)
try:
# Navigate to page
driver.get("https://example.com")
# Collect browser logs
browser_logs = driver.get_log('browser')
performance_logs = driver.get_log('performance')
print("Browser logs:", browser_logs)
print("Performance logs:", performance_logs)
finally:
driver.quit()
Java with Selenium
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.chrome.ChromeDriver;
import org.openqa.selenium.chrome.ChromeOptions;
import org.openqa.selenium.chrome.ChromeDriverService;
import org.openqa.selenium.logging.LogType;
import org.openqa.selenium.logging.LoggingPreferences;
import java.util.logging.Level;
ChromeOptions options = new ChromeOptions();
options.addArguments("--headless");
options.addArguments("--enable-logging");
options.addArguments("--v=1");
options.addArguments("--log-level=0");
// Configure logging preferences
LoggingPreferences logPrefs = new LoggingPreferences();
logPrefs.enable(LogType.BROWSER, Level.ALL);
logPrefs.enable(LogType.DRIVER, Level.ALL);
logPrefs.enable(LogType.PERFORMANCE, Level.ALL);
options.setCapability("goog:loggingPrefs", logPrefs);
// Service configuration
ChromeDriverService service = new ChromeDriverService.Builder()
.withLogFile(new File("./chromedriver.log"))
.withVerbose(true)
.build();
WebDriver driver = new ChromeDriver(service, options);
Puppeteer Configuration
Basic Puppeteer Logging
const puppeteer = require('puppeteer');
(async () => {
const browser = await puppeteer.launch({
headless: 'new', // Use new headless mode
args: [
'--enable-logging',
'--v=1',
'--log-level=0',
'--enable-logging=stderr',
'--no-sandbox',
'--disable-setuid-sandbox'
],
// Enable DevTools logging
devtools: false,
// Capture console events
dumpio: true
});
const page = await browser.newPage();
// Listen to console events
page.on('console', msg => {
console.log('BROWSER LOG:', msg.text());
});
// Listen to page errors
page.on('pageerror', error => {
console.log('PAGE ERROR:', error.message);
});
// Enable request/response logging
await page.setRequestInterception(true);
page.on('request', request => {
console.log('REQUEST:', request.url());
request.continue();
});
page.on('response', response => {
console.log('RESPONSE:', response.url(), response.status());
});
await page.goto('https://example.com');
await browser.close();
})();
Advanced Puppeteer Logging
const puppeteer = require('puppeteer');
const fs = require('fs').promises;
(async () => {
const browser = await puppeteer.launch({
headless: 'new',
args: [
'--enable-logging',
'--v=2',
'--log-level=0',
'--enable-logging=stderr',
'--enable-devtools-experiments',
'--remote-debugging-port=0'
]
});
const page = await browser.newPage();
// Enable runtime and network domains for detailed logging
const client = await page.target().createCDPSession();
await client.send('Runtime.enable');
await client.send('Network.enable');
await client.send('Page.enable');
// Log all CDP events
client.on('Runtime.consoleAPICalled', event => {
console.log('Console API:', event.args.map(arg => arg.value));
});
client.on('Runtime.exceptionThrown', event => {
console.error('Exception:', event.exceptionDetails);
});
client.on('Network.requestWillBeSent', event => {
console.log('Network Request:', event.request.url);
});
await page.goto('https://example.com');
await browser.close();
})();
Playwright Configuration
const { chromium } = require('playwright');
(async () => {
const browser = await chromium.launch({
headless: true,
args: [
'--enable-logging',
'--v=1',
'--log-level=0'
]
});
const context = await browser.newContext();
const page = await context.newPage();
// Enable console logging
page.on('console', msg => console.log('CONSOLE:', msg.text()));
page.on('pageerror', error => console.log('ERROR:', error.message));
await page.goto('https://example.com');
await browser.close();
})();
Log Analysis and Debugging
Understanding Log Levels
--v=0
: Minimal logging (default)--v=1
: Basic debugging information--v=2
: Detailed debugging information--v=3
: Very verbose logging (performance impact)
Common Log Patterns
# Search for specific errors in logs
grep -i "error\|fail\|exception" chromedriver.log
# Monitor logs in real-time
tail -f chromedriver.log
# Filter network-related logs
grep -i "network\|request\|response" chromedriver.log
Log File Locations
- Linux/macOS:
~/.config/chromium/chrome_debug.log
- Windows:
%LOCALAPPDATA%\Chromium\User Data\chrome_debug.log
- Custom: Use
--log-file=/custom/path/debug.log
Environment Variables
# Enable Chrome logging via environment variables
export CHROME_LOG_FILE=/tmp/chrome.log
export CHROME_HEADLESS=1
# Puppeteer debugging
export DEBUG=puppeteer:*
export PUPPETEER_DEBUG=1
Performance Considerations
- Log Level Impact: Higher verbosity levels (
--v=3+
) significantly impact performance - Disk Space: Verbose logs can consume substantial disk space (100MB+ per session)
- Production Use: Disable verbose logging in production environments
- Log Rotation: Implement log rotation for long-running processes
Troubleshooting Common Issues
Chrome Won't Start
# Add these flags for Docker/headless environments
--no-sandbox
--disable-setuid-sandbox
--disable-dev-shm-usage
--disable-gpu
Network Issues
# Enable network logging
--log-net-log=/tmp/net-export.json
--net-log-capture-mode=IncludeCookiesAndCredentials
JavaScript Errors
# Enable console and runtime logging
--enable-logging=stderr
--log-level=0
Verbose logging is a powerful debugging tool that provides deep insights into Chromium's behavior. Start with basic logging (--v=1
) and increase verbosity only when needed for specific debugging scenarios.