Please feel free to send documentation patches to the vbox-dev mailing list.

The VirtualBox/IPRT logging facility

The generic description of the IPRT logging facility is found in Runtime/VBox/log-vbox.cpp.

IPRT log group names (like RT_LDR) and logging flags are found in [/browser/trunk/include/iprt/log.h include/iprt/log.h]
VirtualBox log group names (like DEV_VMM) and flags are found in [/browser/trunk/include/VBox/log.h include/VBox/log.h] Also look for lines like “#define LOG_GROUP LOG_GROUP_DEV_VMM” in files where you want to add logging.

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, and starting with 4.1.8 via VBoxManage debugvm.

Note: If you are wanting to get logging from ring-0 components or from the Guest Additions please see the specific sections about those too (both if you need ring-0 Additions logging).

Note: To enable VBoxSVC release logging please see the dedicated page here.

Examples:

  set VBOX_LOG=em=~0 rem* -rem_mmio       # Enable all EM group logging and all level 1 REM*
                                          # groups logging except REM_MMIO.
  set VBOX_LOG_FLAGS=buffered thread tsc  # Buffer log output, print thread IDs in the log
                                          # statements, print TSC values

  export VBOX_RELEASE_LOG="rem*.e.l.f main gui"
  export VBOX_RELEASE_LOG_FLAGS="buffered thread msprog"
  # Do not limit the number of log entries a guest can send to the release log
  export VBOX_RELEASE_LOG=-dev_vmm_backdoor.restrict

  export VBOX_LOG="dev_vmm.e"
  export VBOX_LOG="rt_ldr.e.f"
  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 [/browser/trunk/src/VBox/Runtime/common/log/log.cpp#L265 Runtime/common/log/log.cpp] around line 265. 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.

Ring-0 logging

Logging from ring-0 context is by default using a hardcoded config found in [/browser/trunk/src/VBox/Runtime/VBox/log-vbox.cpp#L469 Runtime/VBox/log-vbox.cpp]. Since it would generally be more useful to get the ring-0 context log output in the same log file as the ring-3 and raw-mode context log statements when debugging VMM issues on the host, we’ve created (for host ring-0 logging!) a little hack for doing so: Add VBOX_WITH_R0_LOGGING=1 to LocalConfig.kmk or pass it to kmk in the command line. When using this hack the ring-0 logger will mostly use the same settings as the ring-3 logger.

When setting up ring-0 logging on a Linux guest using self-built additions, make sure that your changes to log-vbox.cpp really made it into log-vbox.c in the kernel module source code on the guest. If you wish to enable ring-0 logging on a Linux guest using an official Additions build, you can modify VBox/log-vbox.c in the module source on the guest and force a rebuild and reload of the module. If you wish to pass through guest ring-3 logging to the host, change the make file to build a debug version of the module.

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(...), where 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

Guest Additions logging

To enable the release logging (and debug logging) of the Guest R3 applications into the VMM backdoor:

Windows guests: Create a

  HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\VBoxGuest\LoggingEnabled

registry key with the value 0xFF (DWORD 32bit).

Linux guests: Set /sys/module/vboxguest/r3log_to_host to 1. For Debian-based and RPM guests, install the _sysfsutils package and add
```
  module/vboxguest/parameters/r3_log_to_host = 1
```
to /etc/sysfs.conf. Changing this value at runtime is possible as well.

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), restart the component you wish to log with:

  set VBOX_LOG="all"

Note: You need to have the debug Guest Additions (that is, a debug version of VBoxGuest.) installed on the guest VM in order to make logging from other guest components go to the host log file. *However*, you can still get some logging - to a file on the guest - from release components. See the example of the [X11 guest shared clipboard component](X11Clipboard#GuestLogging).

See the example of the X11 guest shared clipboard component.

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

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

Changing settings using VBoxManage

The VBoxManage command line tool can be used to change the log settings of a running virtual machine. Examples:

  $ VBoxManage debugvm <name> log --release +dev_vga.e.l.f
  $ VBoxManage debugvm <name> log --release -dev_vmm_backdoor.restrict
  $ VBoxManage debugvm <name> logdest --debug stdout
  $ VBoxManage debugvm <name> logflags --release buffered
  $ VBoxManage debugvm <name> show logdbg-settings

Changing settings inside a debugger

Logging settings can be changed at runtime using a debugger. This is mainly useful for VBoxSVC. 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