The VirtualBox/IPRT logging facility

The generic description of the IPRT logging facility is found ​here.

IPRT log group names are found in ​source:trunk/include/iprt/log.h
VirtualBox log group names are found in ​source:trunk/include/VBox/log.h

VirtualBox uses the env.vars VBOX_LOG, VBOX_LOG_DEST and VBOX_LOG_FLAGS to control debug log output and VBOX_RELEASE_LOG, VBOX_RELEASE_LOG_DEST and VBOX_RELEASE_LOG_FLAGS to control release log output. Logging settings can also be changed at runtime using the debugger.

Examples:

set VBOX_LOG=em=~0 rem* -rem_mmio
set VBOX_LOG_FLAGS=buffered thread tsc

export VBOX_RELEASE_LOG="rem*.e.l.f main gui"
export VBOX_RELEASE_LOG_FLAGS="buffered thread msprog"

export VBOX_LOG="dev_vmm"
export VBOX_LOG_FLAGS="msprog"
export VBOX_LOG_DEST="nofile stderr"

The release logging even prints information to a destination when running a release build of component/program. By default this destination is the release log file in the user's VirtualBox home directory, which is rotated on creation. To set the destination, use the environment variable "VBOX_LOG_DEST" for debug logging and "VBOX_RELEASE_LOG_DEST" for release logging, add the prefix "file=" (if logging to a file) or "dir=" (directory) plus the file name / directory. See "Runtime/common/log/log.cpp" around ​line 300. Example:

export VBOX_LOG_DEST="dir=/tmp"

By default, all level 1 release log statements ("LogRel()") cause logging to the release log. For level 2 ("!LogRel2()"), flow logging ("LogRelFlow()") etc to be written out, you need to enable the logging types for the log groups you are interested in - e.g.

VBOX_RELEASE_LOG="+dev_vmm.e.l.f+main.e.l.f"

would enable the "dev_vmm" and "main" release log groups for level 2 and flow logging. Release logging can be handy for debugging remote problems, but should of course be used sparingly in performance-critical code.

To enable ring-0 logging add VBOX_WITH_R0_LOGGING=1 to LocalConfig.kmk or pass it to kmk in the command line (this part is not necessary for guest ring-0 logging) and set up logging preferences in the ​source file src/VBox/Runtime/VBox/log-vbox.cpp.

Some notes about group suffixes:
.eo (.enabledonly) - enabled only;
.e (.enabled) - enabled + level1;
.lX (.levelX) - level X , X 1-6 ;
.l = .l2;
.f (.flow);

named suffixes:
Sometimes core developers use private logging statements which look like Log<Nick>(...), where <Nick> is the developer's nickname. To enable those logging statements you must set the log flag for that developer. For example, for the developer with the nick "NoName" (LogNoName(...) statements in the code) use the suffix
.n = .noname;

To disable logging entirely, use one of:

export VBOX_LOG_DEST=nofile
export VBOX_LOG_FLAGS=disabled
export VBOX_LOG=-all

To enable Guest Additions logging, add to the host environment variables:

set VBOX_LOG="-all+dev_vmm_backdoor.e.l.f+dev_vmm.e.l.f"
set VBOX_LOG_FLAGS="thread tsc"

... and on the guest (for doing this in ring-0 bits see the section on ring-0 above):

set VBOX_LOG="all"

Note: You need to have the debug Guest Additions (that is, a debug version of VBoxGuest.<ext>) installed on the guest VM in order to make logging work with other guest components!

Legacy warning: If "LOG_TO_BACKDOOR" is defined you might end up having cluttered logfiles if you use format specifiers (e.g. "%s") in your debug statements. Undefine / delete this define to use the "regular" IPRT way of logging things.

For Shared Folders (Windows: VBoxSF.sys / VBOXMRXNP.dll)

VBOX_LOG_FLAGS=thread
VBOX_LOG=+hgcm.e.f,+shared_folders.e.f

Logging settings can be changed at runtime using a debugger. Here are two examples with gdb:

(gdb) call RTLogGroupSettings(0, "+drv_nat.e.l.f.l2.l3")
$1 = 0

is the equivalent of passing the environment variable:

VBOX_LOG=+drv_nat.e.l.f.l2.l3

and

(gdb) call RTLogRelDefaultInstance()
$1 = (RTLOGGER *) 0x2be2c30
(gdb) call RTLogFlags(0x2be2c30, "thread")
$2 = 0

is the equivalent of:

VBOX_RELEASE_LOG_FLAGS=thread