How do I enable verbose logging in Headless Chromium for troubleshooting?

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.

Table of contents