= The VirtualBox/IPRT logging facility =

The generic description of the IPRT logging facility is found in [/browser/trunk/src/VBox/Runtime/VBox/log-vbox.cpp#L27 Runtime/VBox/log-vbox.cpp].

IPRT log group names are found in [/browser/trunk/include/iprt/log.h include/iprt/log.h] [[BR]]
!VirtualBox log group names are found in [/browser/trunk/include/VBox/log.h 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, 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 [https://www.virtualbox.org/wiki/VBoxMainLogging here].

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 [/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:[[BR]]
.eo (.enabledonly) - enabled only;[[BR]]
.e (.enabled) - enabled + level1;[[BR]]
.lX (.levelX) - level X , X 1-6 ;[[BR]]
.l = .l2;[[BR]]
.f (.flow);[[BR]]

named suffixes:[[BR]]
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[[BR]]
.n = .noname;[[BR]]

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 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.<ext>) 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 [wiki:X11Clipboard#GuestLogging 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
}}}

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
}}}