Capturing Chromium Module Logs with Command-Line Flags

This article provides a direct guide for developers on using command-line flags to capture targeted, verbose debug logs from the Chromium web browser. By combining basic logging switches with the --vmodule flag, you can isolate specific C++ source files, control verbosity levels, and eliminate the noise of global browser logging during troubleshooting.

1. Enable the Base Logging Mechanism

Before you can capture module-specific logs, you must instruct Chromium to output log data. By default, debug logging is silent. Append one of the following flags to your Chromium launch command:

  • --enable-logging=stderr: Prints the log output directly to your terminal console (standard error). This is the most efficient method for real-time debugging.
  • --enable-logging: Writes the log output to a chrome_debug.log file located inside the browser's user data directory.

2. Target Specific Modules with --vmodule

Using the global verbosity flag (e.g., --v=1) floods the console with data from every component of the browser. To bypass this and target specific areas of the codebase, use the --vmodule flag.

In Chromium, a "module" corresponds to the name of a C++ source file, excluding its file extension (such as .cc or .h). The --vmodule flag overrides the global --v value for the files you specify, activating the VLOG(n) macros within those specific files.

3. Understand the Syntax and Wildcards

The --vmodule flag accepts a comma-separated list of pattern=level arguments.

  • Pattern: The name of the source file (without the extension).
  • Level: An integer (typically 1 through 4) representing the verbosity level. Setting a level of 2 will capture both VLOG(1) and VLOG(2) messages in that file.

You can use wildcards in the pattern to capture multiple related files at once:

  • * matches any sequence of characters.
  • ? matches any single character.
  • Path Matching: If your pattern includes a forward slash (/) or backward slash (\), Chromium matches the pattern against the file's entire directory path instead of just the filename.

4. Practical Examples

To execute these flags, pass them to the Chromium executable via your operating system's terminal or command prompt.

Example A: Isolate a single file To capture level 1 verbose logs strictly from content_settings_pref.cc and output them to the terminal:

chromium --enable-logging=stderr --vmodule=content_settings_pref=1

Example B: Use wildcards for multiple modules To debug WebRTC and media components at different verbosity levels while explicitly silencing global verbose logs:

chromium --enable-logging=stderr --v=0 --vmodule=*webrtc*=2,*media*=1

Example C: Target a specific directory To capture logs from all files inside the chrome/browser/extensions/ directory:

chromium --enable-logging=stderr --vmodule=*/browser/extensions/*=2

5. Important Execution Rules

  • Close Existing Instances: Ensure all running instances of Chromium are completely closed before launching the browser from the command line. If an instance is already running, the new command will simply open a new tab in the existing process and ignore your logging flags.
  • Evaluation Order: Chromium evaluates --vmodule patterns in the exact order they are written. The first pattern that matches a file dictates its logging level. Always place more specific patterns before broad wildcard patterns.